Gitea / Forgejo: Report a run's status

Turns a run’s lifecycle event into a commit status on Gitea or Forgejo: run.started posts pending, run.succeeded success, run.failed failure and run.cancelled error.

• Kind: gitea.report_run_status
• Palette: Integrations, under Gitea / Forgejo
• Credential: a credential of kind bearer, named in credential
• Other Gitea / Forgejo actions: Set commit status

When to use

• A handler that reports every run of a workflow back to the commit that started it, on a self-hosted forge.
• Runs the automatic status reporting doesn’t cover, such as ones you submit with repo and sha in their input.

A run that a handler or a trigger step started directly publishes no lifecycle events to handlers; end that workflow with a set_commit_status step.

Connection (with)

Field	Required	Description
api_base	yes	Include the /api/v1 suffix. Required, since a self-hosted forge has no default host. For example: https://gitea.example.com/api/v1.
context	no	The check’s name on the commit. Defaults to hyperspool. For example: hyperspool/ci.

Input (input)

Field	Type	Required	Description
type	string	yes	The lifecycle event type. Bind the whole envelope instead of the individual fields: input: {“$expr”: “input”}.
payload	object	yes	The lifecycle payload. Needs trigger.repo and trigger.sha, so gate the handler on both: –when ‘has(event.payload.trigger.repo) && has(event.payload.trigger.sha)’.

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: on_run
    type: trigger
    config: { event: run.* }
  - id: report
    type: gitea.report_run_status
    if: "has(input.payload.trigger.repo) && has(input.payload.trigger.sha)"
    config:
      credential: forge
      with:
        api_base: https://git.example.com/api/v1
        context: hyperspool/ci
      input: { $expr: "input" }
edges:
  - { from: on_run, to: report }

input: { $expr: "input" } passes the whole event; the action reads payload.trigger.repo, payload.trigger.sha and payload.run_url from it. It reports the same runs, with the same states, as GitHub’s report_run_status, and works as a handler the same way with --node gitea.report_run_status.

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