Conditional Execution — if:

~11 min · if, conditional, expressions

Level 0Apprentice

0 XP0/101 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

Skip work that doesn't apply

Both jobs and steps support an if: expression. The expression evaluates to truthy / falsy; falsy means skip.

Common patterns:

Branch-specific: if: github.ref == 'refs/heads/main'
Tag-specific: if: startsWith(github.ref, 'refs/tags/v')
Event-specific: if: github.event_name == 'push'
Label-specific: if: contains(github.event.pull_request.labels.*.name, 'deploy')
Path-specific: use paths: filter at workflow level instead.
Status-specific: if: failure(), if: cancelled(), if: always()

Skipped vs failed

An if: that evaluates to false produces skipped, not failed. Skipped jobs don't fail the workflow. They also don't satisfy required status checks if you have branch protection enabled — be careful to not gate a required check behind a conditional, or PRs from a feature branch will hang.

Code

Common conditionals·yaml

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pytest -q

  deploy-staging:
    needs: test
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - run: ./deploy.sh staging

  deploy-prod:
    needs: deploy-staging
    if: startsWith(github.ref, 'refs/tags/v')
    runs-on: ubuntu-latest
    environment: production
    steps:
      - run: ./deploy.sh prod

  cleanup:
    needs: [test, deploy-staging, deploy-prod]
    if: always()
    runs-on: ubuntu-latest
    steps:
      - run: ./cleanup.sh

External links

GitHub — Using conditions to control job execution

Exercise

Audit your repo's required status checks. For each, verify the underlying workflow doesn't skip on common branch types. PRs from new branches should still light up the check, even with if: in play.