`261e5b7`

docs: document runner log finalization API

Authored by mfwolffe <wolffemf@dukes.jmu.edu> 3 days ago

SHA: 261e5b79220bd8378d13a9ef6a85a5f9378c9a20
Parents: 104c4c4
Tree: 292d7cd

3 changed files

Status	File	+	-
M	`docs/internal/actions-runner-api.md`	30	7
A	`docs/public/api/actions-runner.md`	67	0
M	`docs/public/api/overview.md`	7	3

docs/internal/actions-runner-api.mdmodified

  Job JWTs are single-use. Every job endpoint verifies the signature and
  expiry, checks that the path job belongs to the claimed runner/run, and
  then inserts `jti` into `runner_jwt_used`. A replay returns 401. To
 -support multi-step runner flows, successful non-terminal job endpoints
 +support multi-step runner flows, successful in-flight job endpoints
  return `next_token` and `next_token_expires_at`.
  `shithubd-runner` consumes the same token chain: it claims with the
  registration token, marks the job `running` with the first job JWT, then
 -uses the returned `next_token` for the terminal status update. Reusing
 -any consumed job JWT is a replay and must fail with 401.
 +uses each returned `next_token` serially for log chunks, step-status
 +updates, cancel checks, artifact upload requests, and finally the
 +terminal job-status update. Reusing any consumed job JWT is a replay and
 +must fail with 401.
  ## Endpoints
  capped at 512 KiB raw, and appended to `workflow_step_log_chunks`.
  Duplicate `(step_id, seq)` inserts are accepted as idempotent retries.
 +`POST /api/v1/jobs/{id}/steps/{step_id}/status`
++
 +Auth: job JWT. Body:
++
 +```json
 +{"status":"completed","conclusion":"success"}
 +```
++
 +Valid transitions are `queued|running -> running|completed|cancelled|skipped`
 +with idempotent repeats of the target terminal state. Completed and
 +skipped steps require a valid check conclusion; cancelled defaults to
 +`cancelled` when omitted. The endpoint always returns a `next_token`
 +because a completed step is not the end of the job.
++
 +When object storage is configured, terminal step updates enqueue
 +`workflow:finalize_step`. The worker concatenates
 +`workflow_step_log_chunks` in sequence order, uploads the log to
 +`actions/runs/<run_id>/jobs/<job_id>/steps/<step_id>.log`, stores that
 +key and byte count on `workflow_steps`, then deletes the SQL chunks.
++
  `POST /api/v1/jobs/{id}/status`
  Auth: job JWT. Body:
  `workflow_jobs`, rolls up `workflow_runs`, and best-effort updates the
  matching `check_runs` row created by the trigger pipeline.
 -S41d PR1 runner execution supports containerized `run:` steps. `uses:`
 -aliases such as `actions/checkout@v4` and artifact upload/download are
 -reserved for the later S41d slices that add checkout metadata, log
 -streaming, and artifact transfer.
 +S41d PR2 runner execution supports containerized `run:` steps with
 +per-step log streaming and server-side log finalization. `uses:` aliases
 +such as `actions/checkout@v4` and artifact upload/download remain
 +reserved for the later S41d slices that add checkout metadata and
 +artifact transfer.
  `POST /api/v1/jobs/{id}/artifacts/upload`

docs/public/api/actions-runner.mdadded

 +# 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.
++
 +## 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.

docs/public/api/overview.mdmodified

  # API overview
 -shithub exposes a small REST API at `/api/v1/`. It's
 -PAT-authenticated, JSON-bodied, and CSRF-exempt.
 +shithub exposes a small REST API at `/api/v1/`. The user-facing API is
 +PAT-authenticated, JSON-bodied, and CSRF-exempt. The Actions runner API
 +under the same prefix uses runner registration tokens plus per-job JWTs
 +instead of PATs.
  > **Status.** The API is intentionally narrow today. Endpoints
  > currently shipped: `GET /api/v1/user`, the
  Every API request requires a personal access token. See
  [Personal access tokens](../user/personal-access-tokens.md) for
 -how to create one.
 +how to create one. Runner endpoints documented in
 +[Actions runner API](actions-runner.md) are the exception; they reject
 +PATs and require runner credentials.
  ```
  Authorization: Bearer shp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx