Add Actions workflow run monitoring commands #34

stalecontext commented 2026年03月30日 21:15:09 +02:00

Feature Request

Add commands for monitoring and inspecting Forgejo Actions workflow runs from the CLI.

Motivation

Currently there's no way to check CI/Actions status from fj. When debugging CI failures, you have to open the browser, navigate to the run, expand each step, and read logs manually. This is especially painful when iterating on workflow fixes (as we experienced getting our CI pipeline working on Codeberg runners).

Proposed commands

fj actions runs list # list recent workflow runs (status, duration, commit)
fj actions runs view <run-id> # show run details with step-by-step status/timing
fj actions runs logs <run-id> # stream or dump logs for a run/job/step
fj actions runs watch <run-id> # poll a running job until completion
fj actions runs rerun <run-id> # re-trigger a failed run
fj actions runs cancel <run-id> # cancel a running job

Available API endpoints

Verified against the Forgejo source (routers/api/v1/repo/action.go and routers/web/repo/actions/view.go):

REST API (/api/v1):

• GET /repos/{owner}/{repo}/actions/runs - List runs (filterable by event, status, ref, workflow_id)
• GET /repos/{owner}/{repo}/actions/runs/{run_id} - Get a specific run
• GET /repos/{owner}/{repo}/actions/runners/jobs - Search for run jobs (filterable by labels)
• GET /repos/{owner}/{repo}/actions/tasks - List action tasks

Web-only routes (no REST API equivalent):

• GET /:owner/:repo/actions/runs/{run}/jobs/{job}/attempt/{attempt}/logs - Download job logs (file attachment)
• POST /:owner/:repo/actions/runs/{run}/jobs/{job}/rerun - Rerun a specific job
• POST /:owner/:repo/actions/runs/{run}/cancel - Cancel a run

Implementation notes

• Job logs have no REST API endpoint. Logs are only available via the web route as a file download. The CLI will need to hit the web route directly (with auth cookie or token) or we could propose an API endpoint upstream.
• Rerun/cancel are also web-only. Same situation applies.
• Run listing supports pagination (page, limit) and rich filtering (event[], status[], run_number, head_sha, ref, workflow_id).
• Status values: unknown, waiting, running, success, failure, cancelled, skipped, blocked.

Prior art

• gh run list, gh run view, gh run watch from GitHub CLI
• tea CLI has no Actions support yet

## Feature Request Add commands for monitoring and inspecting Forgejo Actions workflow runs from the CLI. ### Motivation Currently there's no way to check CI/Actions status from `fj`. When debugging CI failures, you have to open the browser, navigate to the run, expand each step, and read logs manually. This is especially painful when iterating on workflow fixes (as we experienced getting our CI pipeline working on Codeberg runners). ### Proposed commands ``` fj actions runs list # list recent workflow runs (status, duration, commit) fj actions runs view <run-id> # show run details with step-by-step status/timing fj actions runs logs <run-id> # stream or dump logs for a run/job/step fj actions runs watch <run-id> # poll a running job until completion fj actions runs rerun <run-id> # re-trigger a failed run fj actions runs cancel <run-id> # cancel a running job ``` ### Available API endpoints Verified against the [Forgejo source](https://codeberg.org/forgejo/forgejo) (routers/api/v1/repo/action.go and routers/web/repo/actions/view.go): **REST API (/api/v1):** - GET /repos/{owner}/{repo}/actions/runs - List runs (filterable by event, status, ref, workflow_id) - GET /repos/{owner}/{repo}/actions/runs/{run_id} - Get a specific run - GET /repos/{owner}/{repo}/actions/runners/jobs - Search for run jobs (filterable by labels) - GET /repos/{owner}/{repo}/actions/tasks - List action tasks **Web-only routes (no REST API equivalent):** - GET /:owner/:repo/actions/runs/{run}/jobs/{job}/attempt/{attempt}/logs - Download job logs (file attachment) - POST /:owner/:repo/actions/runs/{run}/jobs/{job}/rerun - Rerun a specific job - POST /:owner/:repo/actions/runs/{run}/cancel - Cancel a run ### Implementation notes - Job logs have no REST API endpoint. Logs are only available via the web route as a file download. The CLI will need to hit the web route directly (with auth cookie or token) or we could propose an API endpoint upstream. - Rerun/cancel are also web-only. Same situation applies. - Run listing supports pagination (page, limit) and rich filtering (event[], status[], run_number, head_sha, ref, workflow_id). - Status values: unknown, waiting, running, success, failure, cancelled, skipped, blocked. ### Prior art - gh run list, gh run view, gh run watch from GitHub CLI - tea CLI has no Actions support yet

stalecontext commented 2026年03月30日 21:26:11 +02:00

Upstream tracking

The missing REST API endpoints are tracked upstream:

• forgejo/forgejo#11859 - feat: new API endpoints for runs/{id}/jobs, jobs/{id}/logs, runs/{id}/logs (open, labeled code/actions + code/api)

Three PRs are in flight:

• forgejo/forgejo#8873 - feat(api): add Actions job details and logs API endpoints (most mature, but stalled since Oct 2025)
• forgejo/forgejo#11329 - WIP: add API endpoint to list jobs for an action run
• forgejo/forgejo#11330 - WIP: add API endpoint to download Actions job logs

No upstream issues exist yet for rerun or cancel REST API endpoints. We may want to file those separately.

For now, runs list and runs view can be implemented using the existing REST API. Logs/rerun/cancel will either need to hit the web routes directly or wait for the upstream API additions.

### Upstream tracking The missing REST API endpoints are tracked upstream: - **forgejo/forgejo#11859** - feat: new API endpoints for `runs/{id}/jobs`, `jobs/{id}/logs`, `runs/{id}/logs` (open, labeled `code/actions` + `code/api`) Three PRs are in flight: - **forgejo/forgejo#8873** - feat(api): add Actions job details and logs API endpoints (most mature, but stalled since Oct 2025) - **forgejo/forgejo#11329** - WIP: add API endpoint to list jobs for an action run - **forgejo/forgejo#11330** - WIP: add API endpoint to download Actions job logs No upstream issues exist yet for rerun or cancel REST API endpoints. We may want to file those separately. For now, `runs list` and `runs view` can be implemented using the existing REST API. Logs/rerun/cancel will either need to hit the web routes directly or wait for the upstream API additions.

okdas commented 2026年04月01日 03:24:04 +02:00

This would be fantastic, honestly missing this. There's a SUPER HACKY workaround to pull logs directly from storage layer (personally using s3-like provider).

This would be fantastic, honestly missing this. There's a SUPER HACKY workaround to pull logs directly from storage layer (personally using s3-like provider).

stalecontext commented 2026年04月02日 01:17:44 +02:00

I'll see if there's a way I can implement this without waiting on direct REST API support. Lemme know if you have any ideas

I'll see if there's a way I can implement this without waiting on direct REST API support. Lemme know if you have any ideas

okdas commented 2026年04月02日 05:31:57 +02:00

On second thought, I feel like it's easier to rely on playwright mcp to grab logs. It's probably better to wait for official API implementation. Too bad they are also adverse to using LLMs :)

On second thought, I feel like it's easier to rely on playwright mcp to grab logs. It's probably better to wait for official API implementation. Too bad they are also adverse to using LLMs :)