forgejo-plumber: skill to debug Forgejo CI/CD failures via the forgejo extension #131

New issue

Closed

opened 2026-08-31 21:47:07 +00:00 by david · 0 comments

david commented

2026-08-31 21:47:07 +00:00

Owner

Summary

Add a new skill, forgejo-plumber, that debugs failed Forgejo Actions (CI/CD) runs using the read-only Actions tools of the forgejo extension: forgejo_action_runs, forgejo_action_run_view, forgejo_action_jobs, forgejo_action_job_log, forgejo_action_run_logs.

The skill is a playbook — it builds nothing; it orchestrates tools that already exist in the extension.

Why

The forgejo extension ships read-only Actions run/job/log tools, but no skill currently teaches how to use them for debugging a failing pipeline.
commit-changes / commit-docs already poll these tools before merging (issue-129, "Checking CI on Forgejo"): forgejo_action_runs head_sha=<sha> → forgejo_action_jobs → forgejo_action_job_log, cache-first logs with refresh: true, v16+ fallback note. The new skill must stay consistent with that section (same tool params, cache/refresh semantics, fallback wording) and may cross-reference it.
git.excelera.net is now Forgejo v16+ (empirically confirmed: forgejo_action_runs returns an empty list, not a 404), so recipes can be smoke-tested against the live instance — no docker/scratch-instance needed.

Scope

In scope — a single trace: failed-run triage

Find the failed run: forgejo_action_runs status=["failure"], narrowed by workflow_id / ref / head_sha
View it: forgejo_action_run_view (status, event, workflow, ref, commit, timestamps)
Find the failed job: forgejo_action_jobs (watch the attempt number on re-runs)
Read the log: forgejo_action_job_log (cache-first; pass refresh: true after a re-run)
Root-cause it: log-grep strategy (first error line vs tail, grep -iE 'error|fail') + common failure categories (dependency install, test failures, secrets, runner/network, workflow-parse)

Plus: a gotchas list, a tool cheat-sheet table, and a version / scope note with smoke-test evidence.

Out of scope (explicit non-goals, with handoff pointers):

Missing / never-triggered runs and stale / 404 logs — one-line pointers only
Re-running workflows and status checks — the extension is read-only; hand off to the web UI / fj pr checks, then return with refresh: true

Structure (full depth, mirroring `victorialogs-debugging`)

Front-matter: name: forgejo-plumber + description
Quick start trace (the 5 steps above)
Log-grep strategy + common failure categories
Gotchas (cache semantics, refresh: true, attempt numbers, pagination limit, status vocabulary, v16+ requirement, token scope)
Tool cheat-sheet table
Version / scope note with smoke-test evidence

Validation

Confirm a registered act_runner exists on the v16 instance — otherwise runs sit at waiting and never produce failure logs.
Push a scratch repo with a deliberately failing workflow (reuse the extension README's "Actions smoke test" checklist).
Run the skill's exact recipes against it: filters, statuses, cache-first log behavior, refresh: true after a re-run.

Distribution

Auto-registered via package.json → "skills": ["./skills"] — no manifest change needed.
Update the README skills table (13 → 14) and the CHANGELOG.

Rollout (per AGENTS.md)

Branch: feature/issue-<N>/forgejo-plumber
Commits: issue-<N>: <summary>
PR: issue-<N>: Add forgejo-plumber skill — body Closes #<N>
Squash-merge and delete the source branch; merge is the owner's call (open the PR, then ask)

Acceptance criteria

skills/forgejo-plumber/SKILL.md written (trace + grep strategy + failure categories + gotchas + cheat-sheet + version note)
Recipes smoke-tested against the live v16 instance (scratch repo + deliberately failing workflow)
README skills table shows 14 skills; CHANGELOG updated
PR opened closing this issue; merge decision left to the owner

### Summary Add a new skill, `forgejo-plumber`, that debugs failed Forgejo Actions (CI/CD) runs using the **read-only** Actions tools of the `forgejo` extension: `forgejo_action_runs`, `forgejo_action_run_view`, `forgejo_action_jobs`, `forgejo_action_job_log`, `forgejo_action_run_logs`. The skill is a **playbook** — it builds nothing; it orchestrates tools that already exist in the extension. ### Why - The `forgejo` extension ships read-only Actions run/job/log tools, but no skill currently teaches how to use them for debugging a failing pipeline. - `commit-changes` / `commit-docs` already poll these tools before merging (issue-129, "Checking CI on Forgejo"): `forgejo_action_runs head_sha=<sha>` → `forgejo_action_jobs` → `forgejo_action_job_log`, cache-first logs with `refresh: true`, v16+ fallback note. The new skill must stay **consistent with that section** (same tool params, cache/refresh semantics, fallback wording) and may cross-reference it. - git.excelera.net is now **Forgejo v16+** (empirically confirmed: `forgejo_action_runs` returns an empty list, not a 404), so recipes can be smoke-tested against the live instance — no docker/scratch-instance needed. ### Scope **In scope — a single trace: failed-run triage** 1. Find the failed run: `forgejo_action_runs status=["failure"]`, narrowed by `workflow_id` / `ref` / `head_sha` 2. View it: `forgejo_action_run_view` (status, event, workflow, ref, commit, timestamps) 3. Find the failed job: `forgejo_action_jobs` (watch the `attempt` number on re-runs) 4. Read the log: `forgejo_action_job_log` (cache-first; pass `refresh: true` after a re-run) 5. Root-cause it: log-grep strategy (first error line vs tail, `grep -iE 'error|fail'`) + common failure categories (dependency install, test failures, secrets, runner/network, workflow-parse) Plus: a gotchas list, a tool cheat-sheet table, and a version / scope note with smoke-test evidence. **Out of scope** (explicit non-goals, with handoff pointers): - Missing / never-triggered runs and stale / 404 logs — one-line pointers only - Re-running workflows and status checks — the extension is read-only; hand off to the web UI / `fj pr checks`, then return with `refresh: true` ### Structure (full depth, mirroring `victorialogs-debugging`) - Front-matter: `name: forgejo-plumber` + `description` - Quick start trace (the 5 steps above) - Log-grep strategy + common failure categories - Gotchas (cache semantics, `refresh: true`, attempt numbers, pagination `limit`, status vocabulary, v16+ requirement, token scope) - Tool cheat-sheet table - Version / scope note with smoke-test evidence ### Validation 1. Confirm a registered `act_runner` exists on the v16 instance — otherwise runs sit at `waiting` and never produce failure logs. 2. Push a scratch repo with a deliberately failing workflow (reuse the extension README's "Actions smoke test" checklist). 3. Run the skill's exact recipes against it: filters, statuses, cache-first log behavior, `refresh: true` after a re-run. ### Distribution - Auto-registered via `package.json` → `"skills": ["./skills"]` — no manifest change needed. - Update the README skills table (13 → 14) and the CHANGELOG. ### Rollout (per AGENTS.md) - Branch: `feature/issue-<N>/forgejo-plumber` - Commits: `issue-<N>: <summary>` - PR: `issue-<N>: Add forgejo-plumber skill` — body `Closes #<N>` - Squash-merge and delete the source branch; **merge is the owner's call** (open the PR, then ask) ### Acceptance criteria - [ ] `skills/forgejo-plumber/SKILL.md` written (trace + grep strategy + failure categories + gotchas + cheat-sheet + version note) - [ ] Recipes smoke-tested against the live v16 instance (scratch repo + deliberately failing workflow) - [ ] README skills table shows 14 skills; CHANGELOG updated - [ ] PR opened closing this issue; merge decision left to the owner

david added the

feature

label

2026-08-31 21:47:07 +00:00

david self-assigned this

2026-08-31 21:47:07 +00:00

david referenced this issue from a pull request that will close it,

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

issue-131: Add forgejo-plumber skill #132

david closed this issue

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