tenseleyflow/shithub / 261e5b7

Browse files

docs: document runner log finalization API

Authored by mfwolffe <wolffemf@dukes.jmu.edu>
SHA
261e5b79220bd8378d13a9ef6a85a5f9378c9a20
Parents
104c4c4
Tree
292d7cd

3 changed files

StatusFile+-
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
@@ -38,13 +38,15 @@ directly for JWT signing.
38
 Job JWTs are single-use. Every job endpoint verifies the signature and
38
 Job JWTs are single-use. Every job endpoint verifies the signature and
39
 expiry, checks that the path job belongs to the claimed runner/run, and
39
 expiry, checks that the path job belongs to the claimed runner/run, and
40
 then inserts `jti` into `runner_jwt_used`. A replay returns 401. To
40
 then inserts `jti` into `runner_jwt_used`. A replay returns 401. To
41
-support multi-step runner flows, successful non-terminal job endpoints
41
+support multi-step runner flows, successful in-flight job endpoints
42
 return `next_token` and `next_token_expires_at`.
42
 return `next_token` and `next_token_expires_at`.
43
43
44
 `shithubd-runner` consumes the same token chain: it claims with the
44
 `shithubd-runner` consumes the same token chain: it claims with the
45
 registration token, marks the job `running` with the first job JWT, then
45
 registration token, marks the job `running` with the first job JWT, then
46
-uses the returned `next_token` for the terminal status update. Reusing
46
+uses each returned `next_token` serially for log chunks, step-status
47
-any consumed job JWT is a replay and must fail with 401.
47
+updates, cancel checks, artifact upload requests, and finally the
48
+terminal job-status update. Reusing any consumed job JWT is a replay and
49
+must fail with 401.
48
 
50
 
49
 ## Endpoints
51
 ## Endpoints
50
 
52
 
@@ -74,6 +76,26 @@ first step in the job receives the chunk. Chunks are base64-decoded,
74
 capped at 512 KiB raw, and appended to `workflow_step_log_chunks`.
76
 capped at 512 KiB raw, and appended to `workflow_step_log_chunks`.
75
 Duplicate `(step_id, seq)` inserts are accepted as idempotent retries.
77
 Duplicate `(step_id, seq)` inserts are accepted as idempotent retries.
76
 
78
 
79
+`POST /api/v1/jobs/{id}/steps/{step_id}/status`
80
+
81
+Auth: job JWT. Body:
82
+
83
+```json
84
+{"status":"completed","conclusion":"success"}
85
+```
86
+
87
+Valid transitions are `queued|running -> running|completed|cancelled|skipped`
88
+with idempotent repeats of the target terminal state. Completed and
89
+skipped steps require a valid check conclusion; cancelled defaults to
90
+`cancelled` when omitted. The endpoint always returns a `next_token`
91
+because a completed step is not the end of the job.
92
+
93
+When object storage is configured, terminal step updates enqueue
94
+`workflow:finalize_step`. The worker concatenates
95
+`workflow_step_log_chunks` in sequence order, uploads the log to
96
+`actions/runs/<run_id>/jobs/<job_id>/steps/<step_id>.log`, stores that
97
+key and byte count on `workflow_steps`, then deletes the SQL chunks.
98
+
77
 `POST /api/v1/jobs/{id}/status`
99
 `POST /api/v1/jobs/{id}/status`
78
 
100
 
79
 Auth: job JWT. Body:
101
 Auth: job JWT. Body:
@@ -87,10 +109,11 @@ Completed jobs require a valid check conclusion. The handler updates
87
 `workflow_jobs`, rolls up `workflow_runs`, and best-effort updates the
109
 `workflow_jobs`, rolls up `workflow_runs`, and best-effort updates the
88
 matching `check_runs` row created by the trigger pipeline.
110
 matching `check_runs` row created by the trigger pipeline.
89
 
111
 
90
-S41d PR1 runner execution supports containerized `run:` steps. `uses:`
112
+S41d PR2 runner execution supports containerized `run:` steps with
91
-aliases such as `actions/checkout@v4` and artifact upload/download are
113
+per-step log streaming and server-side log finalization. `uses:` aliases
92
-reserved for the later S41d slices that add checkout metadata, log
114
+such as `actions/checkout@v4` and artifact upload/download remain
93
-streaming, and artifact transfer.
115
+reserved for the later S41d slices that add checkout metadata and
116
+artifact transfer.
94
 
117
 
95
 `POST /api/v1/jobs/{id}/artifacts/upload`
118
 `POST /api/v1/jobs/{id}/artifacts/upload`
96
 
119
 
docs/public/api/actions-runner.mdadded
@@ -0,0 +1,67 @@ 
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
+## Job log chunks
23
+
24
+```
25
+POST /api/v1/jobs/{id}/logs
26
+```
27
+
28
+Appends one base64-encoded log chunk to a workflow step. The runner uses
29
+the `next_token` returned by each successful call for the next job API
30
+request.
31
+
32
+## Step status
33
+
34
+```
35
+POST /api/v1/jobs/{id}/steps/{step_id}/status
36
+```
37
+
38
+Marks a workflow step running, completed, cancelled, or skipped. Terminal
39
+step updates enqueue server-side log finalization when object storage is
40
+configured.
41
+
42
+## Job status
43
+
44
+```
45
+POST /api/v1/jobs/{id}/status
46
+```
47
+
48
+Marks the claimed job running or terminal, rolls up the workflow run, and
49
+updates the matching check run.
50
+
51
+## Artifact upload
52
+
53
+```
54
+POST /api/v1/jobs/{id}/artifacts/upload
55
+```
56
+
57
+Creates a workflow artifact row and returns a short-lived signed PUT URL
58
+for object storage.
59
+
60
+## Cancel check
61
+
62
+```
63
+POST /api/v1/jobs/{id}/cancel-check
64
+```
65
+
66
+Returns whether the server has requested cancellation for the claimed
67
+job.
docs/public/api/overview.mdmodified
@@ -1,7 +1,9 @@ 
1
 # API overview
1
 # API overview
2
 
2
 
3
-shithub exposes a small REST API at `/api/v1/`. It's
3
+shithub exposes a small REST API at `/api/v1/`. The user-facing API is
4
-PAT-authenticated, JSON-bodied, and CSRF-exempt.
4
+PAT-authenticated, JSON-bodied, and CSRF-exempt. The Actions runner API
5
+under the same prefix uses runner registration tokens plus per-job JWTs
6
+instead of PATs.
5
 
7
 
6
 > **Status.** The API is intentionally narrow today. Endpoints
8
 > **Status.** The API is intentionally narrow today. Endpoints
7
 > currently shipped: `GET /api/v1/user`, the
9
 > currently shipped: `GET /api/v1/user`, the
@@ -15,7 +17,9 @@ PAT-authenticated, JSON-bodied, and CSRF-exempt.
15
 
17
 
16
 Every API request requires a personal access token. See
18
 Every API request requires a personal access token. See
17
 [Personal access tokens](../user/personal-access-tokens.md) for
19
 [Personal access tokens](../user/personal-access-tokens.md) for
18
-how to create one.
20
+how to create one. Runner endpoints documented in
21
+[Actions runner API](actions-runner.md) are the exception; they reject
22
+PATs and require runner credentials.
19
 
23
 
20
 ```
24
 ```
21
 Authorization: Bearer shp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
25
 Authorization: Bearer shp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx