How to Gate CI on a Custom Script Exit Code in GitHub Actions

Sometimes the right check is bespoke; a script that exits non-zero is all GitHub Actions needs to fail a job.

Run your script directly as a step; its exit code becomes the step result, so a non-zero exit fails the job automatically.

Steps

• Write the check as a script that exits 0 on success and non-zero on failure.
• Run it as a step (no extra wiring needed; exit code propagates).
• Use ::error:: to emit a clear failure message before exiting.

Workflow

name: Custom Gate
on: [pull_request]
jobs:
  gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run custom check
        run: |
          if ! ./scripts/policy-check.sh; then
            echo "::error::Policy check failed"
            exit 1
          fi

Notes

• Use set -euo pipefail inside the script so hidden failures still surface.
• On Latchkey managed runners custom gate jobs run cheaper and self-heal if a runner drops.

Related guides