How to Conditionally Skip a Job in GitHub Actions

The if: key gates a job or step on an expression - branch, event, commit message, or a previous job output.

Attach if: to a job or step with a GitHub Actions expression. The job is skipped (not failed) when it evaluates false.

Common conditions

Run only on main, or only for pushes, or skip when the prior job set a flag.

jobs:
  deploy:
    if: ${{ github.ref == 'refs/heads/main' && github.event_name == 'push' }}
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh
        if: ${{ !contains(github.event.head_commit.message, '[skip deploy]') }}

Gotchas

• A skipped *required* job can block merges - use a join job with if: always() to report status.
• GitHub natively honors [skip ci] / [ci skip] in the commit message to skip the whole run for push/PR.
• Use always(), success(), or failure() to run cleanup steps regardless of earlier failures.

Related guides