How to Set a Commit Status from GitHub Actions

By Kaveh Alemi·Latchkey

Post a custom status to a commit via the statuses API so an external gate shows up on the commit and PR.

Use the built-in GITHUB_TOKEN (with statuses: write) to POST to the commit statuses API. The status appears on the commit and the PR checks list with your context name.

Post a status with the API

The token authenticates the statuses API call; context names the check shown on the commit.

permissions:
  statuses: write
jobs:
  external-gate:
    runs-on: ubuntu-latest
    steps:
      - run: |
          curl -sS -X POST \
            -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
            -H "Accept: application/vnd.github+json" \
            "https://api.github.com/repos/${{ github.repository }}/statuses/${{ github.sha }}" \
            -d '{"state":"success","context":"perf-budget","description":"under budget"}'

Gotchas

• The job needs permissions: statuses: write or the API call 403s.
• state must be one of error, failure, pending, success; context is the unique check name.
• Commit statuses are distinct from check runs - to make a status block merges, add it as a required status check in branch protection.

Frequently asked questions

Related guides

References

• GitHub Actions documentation