Porcelain for runs: list, view, logs, watch, cancel, delete, and dispatch #27

New issue

Closed

opened 2026-10-16 23:59:09 -05:00 by jeff · 1 comment

jeff commented

2026-10-16 23:59:09 -05:00

Owner

Work with a repository's runs from the command line, the way gh run and gh workflow run do, instead of through zfj op and run IDs. The terms are in GLOSSARY.md under Forgejo Actions.

Decided

Scope: the runs of one repository, resolved from origin or -R, and dispatching a workflow. Artifacts, secrets, variables and runners — and the org, user and admin operations — stay with zfj op for now.
Shape follows gh: zfj run list|view|watch|cancel|delete and zfj workflow run <file>.
A run is named by its run number, the one the web interface shows, never its ID; each command finds the ID with listActionRuns --run_number, and --json carries both. See docs/adr/0005-runs-are-named-by-run-number.md. A run number is always required: there is no "latest run" default, since one commit can start several runs. A number the repository does not have exits 1, saying no run 43 in jeff/zfj.
No prompts: cancel and delete act at once.
--exit-status on view and watch exits 5 when the run ended in anything but success; 5 joins 0–4 in the usage text and README.
Logs come from the per-job log operation, not the ZIP of the whole run.
workflow run dispatches on the repository's default branch unless --ref says otherwise, and prints the new run's number and URL.

Tickets

Work with a repository's runs from the command line, the way `gh run` and `gh workflow run` do, instead of through `zfj op` and run IDs. The terms are in GLOSSARY.md under **Forgejo Actions**. ## Decided - **Scope**: the runs of one repository, resolved from `origin` or `-R`, and dispatching a workflow. Artifacts, secrets, variables and runners — and the org, user and admin operations — stay with `zfj op` for now. - **Shape follows `gh`**: `zfj run list|view|watch|cancel|delete` and `zfj workflow run <file>`. - **A run is named by its run number**, the one the web interface shows, never its ID; each command finds the ID with `listActionRuns --run_number`, and `--json` carries both. See `docs/adr/0005-runs-are-named-by-run-number.md`. A run number is always required: there is no "latest run" default, since one commit can start several runs. A number the repository does not have exits 1, saying `no run 43 in jeff/zfj`. - **No prompts**: `cancel` and `delete` act at once. - **`--exit-status`** on `view` and `watch` exits **5** when the run ended in anything but `success`; 5 joins 0–4 in the usage text and README. - **Logs** come from the per-job log operation, not the ZIP of the whole run. - **`workflow run`** dispatches on the repository's default branch unless `--ref` says otherwise, and prints the new run's number and URL. ## Tickets - [x] #28 - [x] #29 - [x] #30 - [x] #31 - [x] #32 - [x] #33

jeff referenced this issue

2026-10-16 23:59:29 -05:00

Add zfj run list #28

jeff referenced this issue

2026-10-16 23:59:30 -05:00

Add zfj run view #29

jeff referenced this issue

2026-10-16 23:59:31 -05:00

Print a run's logs with run view --log #30

jeff referenced this issue

2026-10-16 23:59:31 -05:00

Follow a run with zfj run watch #31