GitHub: Set commit status

Sets a commit status on GitHub: the check with a pending, green or red mark beside a commit and on its pull request.

• Kind: github.set_commit_status
• Palette: Integrations, under GitHub
• Credential: a credential of kind bearer, named in credential
• Other GitHub actions: Report a run’s status

When to use

• A job decides for itself what to report, such as a deploy check or a model’s review verdict.
• Reporting from a run the automatic status reporting doesn’t cover, such as one a trigger step or a handler started.

For a repo connected with spool repo connect, --status-credential <name> already posts every build’s status with no step to write. To report a run’s lifecycle from a handler, use report_run_status.

Connection (with)

Field	Required	Description
api_base	no	Set this for GitHub Enterprise. Omit for github.com. For example: https://api.github.com.
context	no	The check’s name on the commit. One context per name, so two pipelines reporting on the same commit need two. Defaults to hyperspool. For example: hyperspool/ci.

Input (input)

Field	Type	Required	Description
repo	string	yes	owner/name.
sha	string	yes	Full commit sha. The statuses API rejects a short one.
state	string	yes	What the check says about the commit. One of "pending", "success", "failure", "error".
target_url	string	no	Where the check links to.
description	string	no	One line shown beside the check.

Settings

Beside with and input in the node’s config.

Field	Type	Required	Description
credential	string	yes	Name of the project credential the action authenticates with.
fail_on_error_status	boolean	no	Treat any 4xx/5xx as a failure. On by default: an action either did its job or did not. Default true.
optional_when_untrusted	boolean	no	Run without the credential when the run is untrusted (a fork pull request), instead of failing. The credential is still withheld.
retry_on	array	no	Status codes that fail the node instead of returning, so its retry: policy applies (e.g. [429, 503]).

Output

The HTTP response. The reply is under body: nodes.<id>.output.body.<field>.

Field	Type	Description
status	integer	The HTTP status code.
headers	object	The response headers.
body	object	The response body, parsed as JSON when it is JSON.
body.context	string
body.id	integer
body.state	string
body.target_url	string
body.url	string	The status on the API.

How it runs

• On an agent with the connector capability. The managed environments have one, so this needs no agent of your own.
• One POST request to an address built from with.
• Any 4xx or 5xx fails the step, unless fail_on_error_status is false. retry: asks again after a 5xx, a 401, 408, 409, 423, 425 or 429, or a 4xx with Retry-After, and not after any other 4xx, which would get the same answer.

Example

version: hyperspool-graph/v1
nodes:
  - id: start
    type: github.set_commit_status
    config:
      credential: forge
      with: { context: hyperspool/deploy }
      input:
        repo: { $expr: "input.repo" }
        sha: { $expr: "input.sha" }
        state: pending
  - id: deploy
    type: shell
    config: { run: ./deploy.sh }
  - id: finish
    type: github.set_commit_status
    config:
      credential: forge
      with: { context: hyperspool/deploy }
      input:
        repo: { $expr: "input.repo" }
        sha: { $expr: "input.sha" }
        state: success
        description: Deployed to production
edges:
  - { from: start, to: deploy }
  - { from: deploy, to: finish }

The credential is a token with the repo:status scope: spool credential set forge --kind bearer. One context is one check on the commit, so two workflows reporting on the same commit need two contexts. Set api_base for GitHub Enterprise.

See Connectors for credentials and versions, and the node reference for every other node.