Conditionals

GitHub Actions allows you to control when jobs and steps run using the if: key. In standard YAML, this often involves writing untyped strings like ${{ github.event_name == 'push' }}.

pygha provides a Python-native way to express these conditions using decorators, context managers, and type-safe expressions.

Job Conditionals

To run an entire job only when specific conditions are met, use the @run_if decorator. You can stack this with the @job decorator.

from pygha import job
from pygha.decorators import run_if
from pygha.expr import github

@job
@run_if(github.event_name == 'push')
def deploy():
    # This job only runs on push events
    ...

Step Conditionals

To run specific steps conditionally, use the when context manager. Any step added inside the block automatically inherits the condition.

from pygha import job
from pygha.steps import run, when, checkout
from pygha.expr import runner

@job
def build():
    checkout()

    # Run specific setup only on Linux
    with when(runner.os == 'Linux'):
        run("sudo apt-get update")
        run("sudo apt-get install -y libpq-dev")

    run("make build")

Nested Conditions

You can nest when blocks. pygha automatically combines them using the standard GitHub Actions && operator.

from pygha.expr import env

with when(runner.os == 'Linux'):
    run("echo Linux")

    with when(env.DEPLOY_TARGET == 'production'):
        # Condition: (runner.os == 'Linux') && (env.DEPLOY_TARGET == 'production')
        run("./deploy_prod.sh")

Expression Builder

The pygha.expr module provides helpers to build expressions without writing raw strings. It supports standard Python operators for boolean logic.

Context Objects

• github: Access GitHub context (e.g., github.ref, github.actor).

• runner: Access Runner context (e.g., runner.os, runner.arch).

• env: Access Environment variables (e.g., env.MY_VAR).

Operators

Python	GitHub Actions	Example
==	==	github.ref == 'main'
!=	!=	github.actor != 'dependabot'
&	&& (AND)	(cond_a) & (cond_b)
|	|| (OR)	(cond_a) | (cond_b)
~	! (NOT)	~(github.actor == 'bot')

Note

When using & and |, you must wrap comparisons in parentheses due to Python’s operator precedence rules.

Correct: (github.ref == 'main') & (runner.os == 'Linux')

Incorrect: github.ref == 'main' & runner.os == 'Linux'

Status Check Functions

pygha exposes standard status check functions as helpers in pygha.expr.

• success(): Returns true if none of the previous steps have failed (default).

• always(): Causes the step or job to run regardless of the status of previous steps.

• failure(): Returns true if any previous step of a job has failed.

from pygha.expr import always, failure

@job
def cleanup_job():
    # ... do work ...

    # This step runs even if the work failed
    with when(always()):
        run("docker logout")

    # Send alert only on failure
    with when(failure()):
        run("./send_slack_alert.sh")