src/actions.ts — metadata queries (listActionRuns, getActionRun, listActionJobs) #114

New issue

Closed

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

david commented

2026-08-29 03:28:15 +00:00

Owner

Summary

New module src/actions.ts with the three live metadata queries: listActionRuns(), getActionRun(), listActionJobs() — read-only, never cached, matching the Forgejo v16 Actions API surface.

Background

Part of the Forgejo Actions tooling feature (tracking issue #111 — branch feature/issue-111/forgejo-actions-tools, commits issue-111: ...). These functions wrap the existing forgejoApiCall() from src/api.ts (same host/owner/repo override + Result<T, ApiError> pattern as src/issues.ts/src/pulls.ts). They power the forgejo_action_runs, forgejo_action_run_view, and forgejo_action_jobs tools. Baseline is Forgejo v16; job details and ?step= / ?q= / ?format=ndjson are v17+ — out of scope.

Documentation Required

docs/reference/forgejo-actions-api/
- https://forgejo.org/docs/latest/user/api/usage/ — Forgejo API usage guide: base URL (/api/v1), Authorization: token <TOKEN> header, token scopes (this feature needs read:repository only), and links to the live swagger.
- https://codeberg.org/forgejo/forgejo/raw/branch/forgejo/templates/swagger/v1_json.tmpl — Forgejo v16 swagger (raw JSON): authoritative definitions of the actions endpoints, incl. the exact runs query params (status, event, ref, head_sha, run_number, workflow_id, page, limit) and response shapes.
- https://codeberg.org/forgejo/forgejo/src/branch/forgejo/routers/api/v1/repo/action.go — server-side implementation of the Actions API handlers; reference for exact filter semantics and response fields.

A separate process downloads these into docs/reference/forgejo-actions-api/ before this issue is implemented. Check that folder for the actual reference material before starting.

Implementation Details

listActionRuns({host, owner, repo, status?, event?, ref?, headSha?, runNumber?, workflowId?, page?, limit?})
- GET /repos/{owner}/{repo}/actions/runs with 1:1 query-param mapping — status / event accept arrays (repeat the param per value), plus ref (e.g. refs/heads/main), head_sha, run_number, workflow_id, page, limit. No server-side actor/time-range filters exist — do not invent them.
- Return the entries plus the total count (from the response, as the swagger specifies).
getActionRun({host, owner, repo, runId}) — GET /repos/{owner}/{repo}/actions/runs/{run_id}.
listActionJobs({host, owner, repo, runId}) — GET /repos/{owner}/{repo}/actions/runs/{run_id}/jobs (no pagination params exist for this endpoint).
Reuse forgejoApiCall's error mapping (404 unknown run/job → ApiError); return Result<T, ApiError>.
Follow the naming/typing style of src/issues.ts (explicit option interfaces, omitUndefined-style payload handling where relevant).

Acceptance Criteria

listActionRuns() builds the URL with the exact path and maps every supported filter to its query param (arrays repeated per value); omitted filters are absent from the query string.
getActionRun() hits /repos/{owner}/{repo}/actions/runs/{run_id} and returns the run.
listActionJobs() hits /repos/{owner}/{repo}/actions/runs/{run_id}/jobs with no query params.
All three return Result<T, ApiError>; a 404 propagates as ApiError (not a thrown exception).
Unit tests (mock fetch via the existing forgejoApiCall test pattern) cover URL/query building for every filter combination and the 404/network error paths.
npm run check passes.

Test Plan

cd extensions/forgejo && npm test — tests/actions.test.ts covers URL/query construction and error mapping with mocked fetch.
Manual (needs a Forgejo v16+ instance; git.excelera.net is v10.0.3 / Gitea 1.22 and does not expose these endpoints): call forgejo_action_runs with status[]=failure, then forgejo_action_run_view on a returned run_id, then forgejo_action_jobs on it, verifying live JSON.

### Summary New module `src/actions.ts` with the three live metadata queries: `listActionRuns()`, `getActionRun()`, `listActionJobs()` — read-only, never cached, matching the Forgejo v16 Actions API surface. ### Background Part of the Forgejo Actions tooling feature (tracking issue **#111** — branch `feature/issue-111/forgejo-actions-tools`, commits `issue-111: ...`). These functions wrap the existing `forgejoApiCall()` from `src/api.ts` (same host/owner/repo override + `Result<T, ApiError>` pattern as `src/issues.ts`/`src/pulls.ts`). They power the `forgejo_action_runs`, `forgejo_action_run_view`, and `forgejo_action_jobs` tools. Baseline is **Forgejo v16**; job details and `?step=` / `?q=` / `?format=ndjson` are v17+ — out of scope. ### Documentation Required - `docs/reference/forgejo-actions-api/` - https://forgejo.org/docs/latest/user/api/usage/ — Forgejo API usage guide: base URL (`/api/v1`), `Authorization: token <TOKEN>` header, token scopes (this feature needs `read:repository` only), and links to the live swagger. - https://codeberg.org/forgejo/forgejo/raw/branch/forgejo/templates/swagger/v1_json.tmpl — Forgejo v16 swagger (raw JSON): authoritative definitions of the actions endpoints, incl. the exact runs query params (`status`, `event`, `ref`, `head_sha`, `run_number`, `workflow_id`, `page`, `limit`) and response shapes. - https://codeberg.org/forgejo/forgejo/src/branch/forgejo/routers/api/v1/repo/action.go — server-side implementation of the Actions API handlers; reference for exact filter semantics and response fields. A separate process downloads these into `docs/reference/forgejo-actions-api/` before this issue is implemented. **Check that folder for the actual reference material before starting.** ### Implementation Details - `listActionRuns({host, owner, repo, status?, event?, ref?, headSha?, runNumber?, workflowId?, page?, limit?})` - `GET /repos/{owner}/{repo}/actions/runs` with **1:1 query-param mapping** — `status` / `event` accept arrays (repeat the param per value), plus `ref` (e.g. `refs/heads/main`), `head_sha`, `run_number`, `workflow_id`, `page`, `limit`. No server-side actor/time-range filters exist — do not invent them. - Return the entries plus the total count (from the response, as the swagger specifies). - `getActionRun({host, owner, repo, runId})` — `GET /repos/{owner}/{repo}/actions/runs/{run_id}`. - `listActionJobs({host, owner, repo, runId})` — `GET /repos/{owner}/{repo}/actions/runs/{run_id}/jobs` (no pagination params exist for this endpoint). - Reuse `forgejoApiCall`'s error mapping (404 unknown run/job → `ApiError`); return `Result<T, ApiError>`. - Follow the naming/typing style of `src/issues.ts` (explicit option interfaces, `omitUndefined`-style payload handling where relevant). ### Acceptance Criteria - [ ] `listActionRuns()` builds the URL with the exact path and maps every supported filter to its query param (arrays repeated per value); omitted filters are absent from the query string. - [ ] `getActionRun()` hits `/repos/{owner}/{repo}/actions/runs/{run_id}` and returns the run. - [ ] `listActionJobs()` hits `/repos/{owner}/{repo}/actions/runs/{run_id}/jobs` with no query params. - [ ] All three return `Result<T, ApiError>`; a 404 propagates as `ApiError` (not a thrown exception). - [ ] Unit tests (mock `fetch` via the existing `forgejoApiCall` test pattern) cover URL/query building for every filter combination and the 404/network error paths. - [ ] `npm run check` passes. ### Test Plan - `cd extensions/forgejo && npm test` — `tests/actions.test.ts` covers URL/query construction and error mapping with mocked fetch. - Manual (needs a **Forgejo v16+** instance; `git.excelera.net` is v10.0.3 / Gitea 1.22 and does not expose these endpoints): call `forgejo_action_runs` with `status[]=failure`, then `forgejo_action_run_view` on a returned `run_id`, then `forgejo_action_jobs` on it, verifying live JSON.

david added this to the M6 - Actions tooling (runs/jobs/logs + cache) milestone

2026-08-29 03:28:15 +00:00

david added the

feature

label

2026-08-29 03:28:15 +00:00

david referenced this issue

2026-08-29 03:28:50 +00:00

Register 5 forgejo_action_* tools in src/index.ts #117

david referenced this issue

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

Tests — cache cycle, URL building, error mapping, ZIP guards #118