How to Set a Commit Status from a Script in GitHub Actions

When a check lives outside a normal job, posting a commit status puts its result where reviewers expect it.

Call the statuses API with gh api (or curl) to set a state and context on the commit SHA.

Steps

• Grant statuses: write permission to the job.
• Run your external check and capture its result.
• POST to /repos/{owner}/{repo}/statuses/{sha} with the state and context.

Workflow

name: Custom Status
on: [pull_request]
permissions:
  statuses: write
jobs:
  status:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Post commit status
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh api repos/${{ github.repository }}/statuses/${{ github.sha }} \
            -f state=success -f context=custom/check \
            -f description='External check passed'

Notes

• Use the PR head SHA (github.event.pull_request.head.sha) on pull_request events if you need the branch tip.
• On Latchkey managed runners status-posting jobs run cheaper and self-heal if a runner dies.

Related guides