tenseleyflow/shithub / 8108c6b

Browse files

docs/actions: document workflow reruns

Authored by mfwolffe <wolffemf@dukes.jmu.edu>
SHA
8108c6bdf785d2079751c1efd79edc293c36e6c2
Parents
561824f
Tree
3bb9ff5

3 changed files

StatusFile+-
M docs/internal/actions-runner-api.md 17 0
M docs/internal/actions-schema.md 5 1
M docs/internal/runbooks/actions-runner.md 14 0
docs/internal/actions-runner-api.mdmodified
@@ -165,6 +165,23 @@ Running jobs keep `status = running` and get
165165
 `cancel-check`, kills the active container, then reports terminal
166166
 `cancelled`.
167167
168
+`POST /api/v1/runs/{id}/rerun`
169
+
170
+Auth: PAT with `repo:write`, and the actor must have write permission on
171
+the repository that owns the workflow run. Browser UI forms use
172
+CSRF-protected repo routes for the same operation.
173
+
174
+Only terminal workflow runs are rerunnable. A re-run reads the original
175
+workflow file from the source run's `head_sha`, not from the current
176
+branch tip, then enqueues a new `workflow_runs` row with:
177
+
178
+- the same `repo_id`, `workflow_file`, `head_sha`, `head_ref`, event,
179
+  and event payload
180
+- `actor_user_id` set to the user requesting the re-run
181
+- `parent_run_id` set to the source run
182
+- a fresh `trigger_event_id` in the `rerun:<source_run_id>:<random>`
183
+  namespace
184
+
168185
 `POST /api/v1/jobs/{id}/cancel-check`
169186
170187
 Auth: job JWT. Returns:
docs/internal/actions-schema.mdmodified
@@ -372,6 +372,10 @@ Other admin surfaces are scoped to later sub-sprints:
372372
 - S41g: `POST /api/v1/jobs/{id}/cancel` and the repository run-detail
373373
   UI request cancellation. Running jobs flip `cancel_requested`; queued
374374
   jobs are made terminal immediately.
375
+- S41g: `POST /api/v1/runs/{id}/rerun` and the repository run-detail
376
+  UI re-run completed/cancelled runs. Re-runs read the workflow YAML
377
+  from the original run's `head_sha`, create a fresh queued
378
+  `workflow_runs` row, and set `parent_run_id` to the source run.
375379
376380
 ## Trigger pipeline (S41b)
377381
@@ -419,7 +423,7 @@ The trigger handler does `INSERT … ON CONFLICT DO NOTHING` so:
419423
 - Worker retries (the same push_process replay) → no duplicate runs.
420424
 - Admin replays via `shithubd admin run-job workflow:trigger ...`
421425
   → no duplicate runs.
422
-- Re-runs (the future "Re-run" button) explicitly construct a NEW
426
+- Re-runs explicitly construct a NEW
423427
   trigger_event_id (`rerun:<original_run_id>:<request_uuid>`) and
424428
   chain back via `parent_run_id`. History is preserved, no
425429
   collision.
docs/internal/runbooks/actions-runner.mdmodified
@@ -153,6 +153,20 @@ running, the next runner cancel check returns `{"cancelled":true}`, the
153153
 runner kills the active container, and the terminal job status becomes
154154
 `cancelled`.
155155
156
+Re-run smoke: after a completed or cancelled workflow run, a repo-write
157
+PAT can enqueue a new run from the original workflow file at the
158
+original commit:
159
+
160
+```sh
161
+curl -fsS "$BASE/api/v1/runs/$RUN_ID/rerun" \
162
+  -H "Authorization: Bearer $PAT_WITH_REPO_WRITE" \
163
+  -X POST
164
+```
165
+
166
+Expected response includes a new `run_id`, the new `run_index`, and
167
+`parent_run_id` equal to the source run. Confirm the new row has the
168
+same `head_sha` as the source run.
169
+
156170
 Replay check: reusing the log token after the log call must fail with
157171
 401 because its `jti` is already present in `runner_jwt_used`.
158172