issue-131: Add forgejo-plumber skill #132

Merged

david merged 1 commit from feature/issue-131/forgejo-plumber into main

2026-08-31 22:01:05 +00:00

david commented

2026-08-31 21:57:49 +00:00

Owner

Closes #131

Adds the forgejo-plumber skill: a playbook for debugging failed Forgejo Actions runs through the read-only Actions tools of the forgejo extension.

What's in it

Quick start: failed-run triage — one trace, five steps: forgejo_action_runs status=["failure"] (narrowed by workflow_id / ref / head_sha) → forgejo_action_run_view → forgejo_action_jobs (watch attempt numbers) → forgejo_action_job_log (cache-first, refresh: true after a re-run) → root-cause.
Log-grep strategy — first error line vs tail, with the act-runner outcome lines (⚙️ exitcode, 🏁 Job failed) and a table of common failure categories (dependency install, test failures, secrets, runner/network, workflow-parse).
Gotchas — cache semantics, refresh: true, attempt numbers, pagination limit, status vocabulary, waiting = no runner, v16+ requirement with web-UI fallback, read:repository token scope, and the v16 no-re-run-API finding.
Tool cheat-sheet table + version/scope note with smoke-test evidence.

Consistency

Tool params, cache/refresh semantics, and the v16+ fallback wording match the Checking CI on Forgejo section in commit-changes / commit-docs (issue-129), and the skill cross-references it as the "is CI green" companion.

Validation (live smoke test)

All recipes were run against the live instance with the real extension tools:

Instance is Forgejo v16.0.3 (16.0.3+gitea-1.22.0) with 4 registered act_runners (act_runner v13.0.0 — confirmed via /admin/actions/runners and the log's Runner … version:v13.0.0 line).
Scratch repo david/forgejo-plumber-smoke with a deliberately failing workflow: run #1 (ci.yml, push) → failure; job build failed (fake compile error, exit 1) while sibling job test passed. A fix commit produced run #2 → success.
Exercised: status/workflow_id/ref/head_sha filters, run_view, jobs (attempt 1), job_log cache-first (cached: false → repeat cached: true), refresh: true (re-download confirmed), run_logs (ZIP + per-job extraction into ~/.cache/forgejo-actions), and the 404 error shape.
Verified against the v16 swagger: no re-run endpoint in v16 (only cancel/delete/logs/jobs) — re-running happens in the web UI, then refresh: true. Documented in the skill.

Files

skills/forgejo-plumber/SKILL.md (new)
README.md — skills table 13 → 14 (table row, /skills mention, repository layout)
CHANGELOG.md — Added entry

Squash-merge and delete the source branch. Merge decision left to the owner.

Closes #131 Adds the `forgejo-plumber` skill: a playbook for debugging failed Forgejo Actions runs through the read-only Actions tools of the `forgejo` extension. ## What's in it - **Quick start: failed-run triage** — one trace, five steps: `forgejo_action_runs status=["failure"]` (narrowed by `workflow_id` / `ref` / `head_sha`) → `forgejo_action_run_view` → `forgejo_action_jobs` (watch `attempt` numbers) → `forgejo_action_job_log` (cache-first, `refresh: true` after a re-run) → root-cause. - **Log-grep strategy** — first error line vs tail, with the act-runner outcome lines (`⚙️ exitcode`, `🏁 Job failed`) and a table of common failure categories (dependency install, test failures, secrets, runner/network, workflow-parse). - **Gotchas** — cache semantics, `refresh: true`, attempt numbers, pagination `limit`, status vocabulary, `waiting` = no runner, v16+ requirement with web-UI fallback, `read:repository` token scope, and the v16 **no-re-run-API** finding. - **Tool cheat-sheet** table + version/scope note with smoke-test evidence. ## Consistency Tool params, cache/refresh semantics, and the v16+ fallback wording match the *Checking CI on Forgejo* section in `commit-changes` / `commit-docs` (issue-129), and the skill cross-references it as the "is CI green" companion. ## Validation (live smoke test) All recipes were run against the live instance with the real extension tools: - Instance is **Forgejo v16.0.3** (`16.0.3+gitea-1.22.0`) with **4 registered act_runners** (act_runner v13.0.0 — confirmed via `/admin/actions/runners` and the log's `Runner … version:v13.0.0` line). - Scratch repo `david/forgejo-plumber-smoke` with a deliberately failing workflow: run #1 (`ci.yml`, push) → `failure`; job `build` failed (fake compile error, exit 1) while sibling job `test` passed. A fix commit produced run #2 → `success`. - Exercised: `status`/`workflow_id`/`ref`/`head_sha` filters, `run_view`, `jobs` (attempt 1), `job_log` cache-first (`cached: false` → repeat `cached: true`), `refresh: true` (re-download confirmed), `run_logs` (ZIP + per-job extraction into `~/.cache/forgejo-actions`), and the 404 error shape. - Verified against the v16 swagger: **no re-run endpoint in v16** (only cancel/delete/logs/jobs) — re-running happens in the web UI, then `refresh: true`. Documented in the skill. ## Files - `skills/forgejo-plumber/SKILL.md` (new) - `README.md` — skills table 13 → 14 (table row, `/skills` mention, repository layout) - `CHANGELOG.md` — Added entry Squash-merge and delete the source branch. Merge decision left to the owner.

david added the

feature

label

2026-08-31 21:57:49 +00:00

david self-assigned this

2026-08-31 21:57:50 +00:00

david added 1 commit

2026-08-31 21:57:50 +00:00