How to Create a Commit Status from CI with the Status API

The statuses API attaches a state (success, failure, pending, error) to a commit SHA under a named context.

POST to /repos/<owner>/<repo>/statuses/<sha> with state, context, description, and target_url. This is how external CI and custom checks report a result GitHub can require.

Steps

Get the commit SHA to report against.
POST a state and a context string to the statuses endpoint.
Optionally add target_url linking to the run and a description.

Create a status

Terminal

curl -X POST \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/acme/widget/statuses/$GITHUB_SHA \
  -d '{"state":"success","context":"lint","description":"0 warnings","target_url":"https://ci.example.com/42"}'

Gotchas

The token needs the repo:status (or statuses: write) permission.
The context is the identity of the check; keep it stable so branch protection can require it.

Related guides

How to Choose Between Check Runs and Commit StatusesUnderstand the difference between GitHub check runs and commit statuses, and create a rich check run with the… How to Require Status Checks with Branch ProtectionRequire passing status checks before merging by adding them to a branch protection rule, and understand why a… How to Emit Annotations from CI in GitHub ActionsEmit inline error and warning annotations from a GitHub Actions job with the error and warning workflow comma…