Actions runner API
The Actions runner API is mounted under /api/v1, but it is not a
personal-access-token surface. Operators register runners with
shithubd admin runner register; runner processes authenticate
heartbeats with that registration token and authenticate job updates
with short-lived, single-use job JWTs returned by the heartbeat claim.
These endpoints are intended for shithubd-runner, not browser clients
or third-party integrations.
Runner heartbeat
POST /api/v1/runners/heartbeat
Claims one queued workflow job for a registered runner when labels and
capacity match. Returns 204 No Content when no job is available, or
200 OK with a job payload and job JWT.
The runner may include host_name and version in the heartbeat body
for operator diagnostics. Drained runners return 204 No Content and do
not claim new jobs. Revoked runners receive 401 Unauthorized, and job
JWTs previously minted for that runner are rejected.
Job log chunks
POST /api/v1/jobs/{id}/logs
Appends one base64-encoded log chunk to a workflow step. The runner uses
the next_token returned by each successful call for the next job API
request.
Step status
POST /api/v1/jobs/{id}/steps/{step_id}/status
Marks a workflow step running, completed, cancelled, or skipped. Terminal step updates enqueue server-side log finalization when object storage is configured.
Job status
POST /api/v1/jobs/{id}/status
Marks the claimed job running or terminal, rolls up the workflow run, and updates the matching check run.
Artifact upload
POST /api/v1/jobs/{id}/artifacts/upload
Creates a workflow artifact row and returns a short-lived signed PUT URL for object storage.
Cancel check
POST /api/v1/jobs/{id}/cancel-check
Returns whether the server has requested cancellation for the claimed job.
View source
| 1 | # Actions runner API |
| 2 | |
| 3 | The Actions runner API is mounted under `/api/v1`, but it is not a |
| 4 | personal-access-token surface. Operators register runners with |
| 5 | `shithubd admin runner register`; runner processes authenticate |
| 6 | heartbeats with that registration token and authenticate job updates |
| 7 | with short-lived, single-use job JWTs returned by the heartbeat claim. |
| 8 | |
| 9 | These endpoints are intended for `shithubd-runner`, not browser clients |
| 10 | or third-party integrations. |
| 11 | |
| 12 | ## Runner heartbeat |
| 13 | |
| 14 | ``` |
| 15 | POST /api/v1/runners/heartbeat |
| 16 | ``` |
| 17 | |
| 18 | Claims one queued workflow job for a registered runner when labels and |
| 19 | capacity match. Returns `204 No Content` when no job is available, or |
| 20 | `200 OK` with a job payload and job JWT. |
| 21 | |
| 22 | The runner may include `host_name` and `version` in the heartbeat body |
| 23 | for operator diagnostics. Drained runners return `204 No Content` and do |
| 24 | not claim new jobs. Revoked runners receive `401 Unauthorized`, and job |
| 25 | JWTs previously minted for that runner are rejected. |
| 26 | |
| 27 | ## Job log chunks |
| 28 | |
| 29 | ``` |
| 30 | POST /api/v1/jobs/{id}/logs |
| 31 | ``` |
| 32 | |
| 33 | Appends one base64-encoded log chunk to a workflow step. The runner uses |
| 34 | the `next_token` returned by each successful call for the next job API |
| 35 | request. |
| 36 | |
| 37 | ## Step status |
| 38 | |
| 39 | ``` |
| 40 | POST /api/v1/jobs/{id}/steps/{step_id}/status |
| 41 | ``` |
| 42 | |
| 43 | Marks a workflow step running, completed, cancelled, or skipped. Terminal |
| 44 | step updates enqueue server-side log finalization when object storage is |
| 45 | configured. |
| 46 | |
| 47 | ## Job status |
| 48 | |
| 49 | ``` |
| 50 | POST /api/v1/jobs/{id}/status |
| 51 | ``` |
| 52 | |
| 53 | Marks the claimed job running or terminal, rolls up the workflow run, and |
| 54 | updates the matching check run. |
| 55 | |
| 56 | ## Artifact upload |
| 57 | |
| 58 | ``` |
| 59 | POST /api/v1/jobs/{id}/artifacts/upload |
| 60 | ``` |
| 61 | |
| 62 | Creates a workflow artifact row and returns a short-lived signed PUT URL |
| 63 | for object storage. |
| 64 | |
| 65 | ## Cancel check |
| 66 | |
| 67 | ``` |
| 68 | POST /api/v1/jobs/{id}/cancel-check |
| 69 | ``` |
| 70 | |
| 71 | Returns whether the server has requested cancellation for the claimed |
| 72 | job. |