README.md — Actions tools table, examples, caveats #119

New issue

Closed

opened 2026-08-29 03:29:12 +00:00 by david · 1 comment

david commented

2026-08-29 03:29:12 +00:00

Owner

Summary

Add the Actions tooling documentation to extensions/forgejo/README.md: a 5-tool table with parameters, a failure-debugging example flow, and the cache/scope/version caveats.

Background

Part of the Forgejo Actions tooling feature (tracking issue #111). Documentation is the explicit last step — it lands only after code + tests are green (#118). Extend the existing README structure (Setup, Install, Tool list, Examples, Caveats) with the Actions section.

Implementation Details

Add an "Actions tools" table (5 tools) with params:
- forgejo_action_runs — all filters (status[], event[], ref, head_sha, run_number, workflow_id, page, limit).
- forgejo_action_run_view — run_id.
- forgejo_action_jobs — run_id.
- forgejo_action_job_log — run_id, job_id, attempt?, refresh?.
- forgejo_action_run_logs — run_id, refresh?.
Examples: find failed runs (forgejo_action_runs with status[]=failure) → pick a run → forgejo_action_job_log → show returned path + cached flag; second call cached, refresh: true after re-run.
Caveats section:
- Cache location: ~/.cache/forgejo-actions by default, override with FORGEJO_ACTIONS_CACHE_DIR.
- Token scope: read:repository only — nothing is written to Forgejo.
- Baseline: Forgejo v16+ — the runs/jobs/logs endpoints do not exist on older instances (e.g. v10 / gitea-1.22).
- v17+ features (job details, ?step= / ?q= / ?format=ndjson) are out of scope.
- refresh semantics: pass it after a workflow re-run or for in-progress runs.

Acceptance Criteria

README has a 5-tool Actions table with all parameters and return shapes.
At least one end-to-end failure-debugging example (runs → job → log) with expected output.
All caveats (cache dir, read:repository, v16 baseline, v17 out of scope, refresh) are present.
No statements contradict the shipped implementation or DESIGN.md (#120).

Test Plan

Read the rendered README (Forgejo web view) and follow the example flow on a v16+ instance.
Cross-check every tool name/param against src/index.ts registration.

### Summary Add the Actions tooling documentation to `extensions/forgejo/README.md`: a 5-tool table with parameters, a failure-debugging example flow, and the cache/scope/version caveats. ### Background Part of the Forgejo Actions tooling feature (tracking issue **#111**). Documentation is the **explicit last step** — it lands only after code + tests are green (**#118**). Extend the existing README structure (Setup, Install, Tool list, Examples, Caveats) with the Actions section. ### Implementation Details - Add an "Actions tools" table (5 tools) with params: - `forgejo_action_runs` — all filters (`status[]`, `event[]`, `ref`, `head_sha`, `run_number`, `workflow_id`, `page`, `limit`). - `forgejo_action_run_view` — `run_id`. - `forgejo_action_jobs` — `run_id`. - `forgejo_action_job_log` — `run_id`, `job_id`, `attempt?`, `refresh?`. - `forgejo_action_run_logs` — `run_id`, `refresh?`. - Examples: find failed runs (`forgejo_action_runs` with `status[]=failure`) → pick a run → `forgejo_action_job_log` → show returned `path` + `cached` flag; second call cached, `refresh: true` after re-run. - Caveats section: - Cache location: `~/.cache/forgejo-actions` by default, override with `FORGEJO_ACTIONS_CACHE_DIR`. - Token scope: `read:repository` only — nothing is written to Forgejo. - Baseline: Forgejo **v16+** — the runs/jobs/logs endpoints do not exist on older instances (e.g. v10 / gitea-1.22). - v17+ features (job details, `?step=` / `?q=` / `?format=ndjson`) are out of scope. - `refresh` semantics: pass it after a workflow re-run or for in-progress runs. ### Acceptance Criteria - [ ] README has a 5-tool Actions table with all parameters and return shapes. - [ ] At least one end-to-end failure-debugging example (runs → job → log) with expected output. - [ ] All caveats (cache dir, `read:repository`, v16 baseline, v17 out of scope, `refresh`) are present. - [ ] No statements contradict the shipped implementation or DESIGN.md (#120). ### Test Plan - Read the rendered README (Forgejo web view) and follow the example flow on a v16+ instance. - Cross-check every tool name/param against `src/index.ts` registration.

david added this to the M7 - Actions documentation (last step) milestone

2026-08-29 03:29:12 +00:00

david added the

documentation

label

2026-08-29 03:29:12 +00:00

david referenced this issue

2026-08-29 03:29:23 +00:00

DESIGN.md — tool matrix, API table, version requirements #120

david referenced this issue

2026-08-29 03:29:32 +00:00

Final review — docs consistency + npm run check/test green #121

david closed this issue

2026-09-18 06:09:08 +00:00

david commented

2026-09-18 06:09:15 +00:00

Author

Owner

Closing — the work described here was already implemented and merged to main (commit ee2b5ac, part of the Actions tooling batch under tracking issue #111).

Verified against current repo state:

✅ 5-tool Actions table in extensions/forgejo/README.md with all params; every tool name/param cross-checked against its registration in src/index.ts.
✅ End-to-end failure-debugging example (runs → jobs → job log) with expected output, plus a dedicated "Actions smoke test" section including the refresh: true step.
✅ All caveats present: cache dir + FORGEJO_ACTIONS_CACHE_DIR, read:repository scope, v16 baseline, v17+ out of scope, refresh semantics.
✅ No contradictions with the shipped implementation or docs/DESIGN.md (#120).

Closing — the work described here was already implemented and merged to `main` (commit `ee2b5ac`, part of the Actions tooling batch under tracking issue #111). Verified against current repo state: - ✅ 5-tool Actions table in `extensions/forgejo/README.md` with all params; every tool name/param cross-checked against its registration in `src/index.ts`. - ✅ End-to-end failure-debugging example (runs → jobs → job log) with expected output, plus a dedicated "Actions smoke test" section including the `refresh: true` step. - ✅ All caveats present: cache dir + `FORGEJO_ACTIONS_CACHE_DIR`, `read:repository` scope, v16 baseline, v17+ out of scope, `refresh` semantics. - ✅ No contradictions with the shipped implementation or `docs/DESIGN.md` (#120).

david referenced this issue

2026-09-18 06:14:27 +00:00

DESIGN.md — tool matrix, API table, version requirements #120

david referenced this issue

2026-09-18 06:44:46 +00:00

Open PR — issue-111: add forgejo actions tools #122