feat: take advantage of Forgejo 15.0 Actions/runner changes #30

New issue

Open

opened 2026-05-01 06:04:48 +00:00 by rcsheets · 1 comment

rcsheets commented

2026-05-01 06:04:48 +00:00

Owner

Forgejo 15.0 (release notes, full changelog) introduced several runner-side changes that the operator could meaningfully exploit. Grouping by impact for triage.

High-impact opportunities

Ephemeral runners

Forgejo now supports runners that execute exactly one job and then terminate, with their registration credentials auto-deleted. The runner exposes a new one-job command for this mode, and registration accepts an "ephemeral": true parameter.

This is a near-perfect fit for a Kubernetes operator: rather than maintaining long-lived Deployments of runners, the operator could create a Job (or pod) per queued workflow run, scale to zero when idle, and never reuse a pod across jobs. Eliminates "leaky state between jobs" classes of bugs (which is partly why we currently rebuild the storage path on every run in pr-reviewer's build-push).

Worth designing for explicitly — what does a RunnerPool CR look like when "pool" really means "controller for ephemeral runner Jobs"? Do we keep the long-lived pool model alongside as a fallback?

OIDC workload identity federation

Runners can now obtain short-lived signed JWTs to authenticate to external systems (Harbor, OpenBao, etc.) instead of relying on static secrets baked into the runner pod or pulled from OpenBao at job start. Requires Forgejo Runner v12.5.0+.

If we adopt this, the OpenBao step in pr-reviewer's build-push.yaml (and equivalents) gets a lot simpler — no more "fetch a service-account token, exchange it for a Bao token, exchange that for Harbor creds, write a docker config." The runner mints a JWT, exchanges with OpenBao directly via OIDC auth method, done. Adjacent work in OpenBao to add a JWT/OIDC auth role for the Forgejo issuer.

New HTTP API for runner registration

Forgejo 15.0 adds a proper HTTP API endpoint for runner registration and deprecates the old token-acquisition endpoints. The operator currently relies on the older flow (presumably). Migrate before the deprecated endpoints are removed in a future release.

Medium-impact / hygiene

Pin runner image to ≥ v12.5.0: required for OIDC and one-job. Audit current pinned versions in runner pool definitions; bump as needed.
Error handling: 403 → 404: Forgejo now returns 404 (not 403) for resources the token can't see, to prevent enumeration. Any operator code that distinguishes "missing" from "forbidden" needs adjustment.
Permission scope tightening: template generation/deletion APIs and admin-level permissions on repo-specific tokens. Verify the operator's service token doesn't rely on now-removed admin scopes.

Low-impact / informational

Runner search by UUID + new filter/visibility flags on runner list endpoints — useful for reconciliation logic when checking whether currently-registered runners match desired CR state.
Multiple-tasks-per-fetch and job-specific runner requests are runner-internal optimizations; nothing for the operator to wire up, but they shift the cost model in favor of larger pools / longer-lived runners staying interesting alongside ephemeral ones.
Workflow-side changes (reusable workflow expansion, dispatch input limit raised to 100, scheduled workflow timezone, etc.) — workflow authors' concern, not the operator's, but worth keeping in mind when documenting.

Suggested ordering

Bump runner image version to 12.5.x in the existing pool definitions. Smallest blast radius; unblocks everything below.
Migrate registration to the new HTTP API. Pure plumbing change; preserves current architecture.
Add ephemeral runner mode as a new option on the RunnerPool CR (alongside the existing long-lived shape).
OIDC workload identity — design the OpenBao auth role first, then a workflow proof-of-concept (probably in pr-reviewer since it's the one with the most secret-handling), then expose via operator config.

Forgejo 15.0 ([release notes](https://forgejo.org/2026-04-release-v15-0/), [full changelog](https://codeberg.org/forgejo/forgejo/raw/branch/forgejo/release-notes-published/15.0.0.md)) introduced several runner-side changes that the operator could meaningfully exploit. Grouping by impact for triage. ## High-impact opportunities ### Ephemeral runners Forgejo now supports runners that execute exactly one job and then terminate, with their registration credentials auto-deleted. The runner exposes a new `one-job` command for this mode, and registration accepts an `"ephemeral": true` parameter. This is a near-perfect fit for a Kubernetes operator: rather than maintaining long-lived `Deployment`s of runners, the operator could create a `Job` (or pod) per queued workflow run, scale to zero when idle, and never reuse a pod across jobs. Eliminates "leaky state between jobs" classes of bugs (which is partly why we currently rebuild the storage path on every run in `pr-reviewer`'s build-push). Worth designing for explicitly — what does a `RunnerPool` CR look like when "pool" really means "controller for ephemeral runner Jobs"? Do we keep the long-lived pool model alongside as a fallback? ### OIDC workload identity federation Runners can now obtain short-lived signed JWTs to authenticate to external systems (Harbor, OpenBao, etc.) instead of relying on static secrets baked into the runner pod or pulled from OpenBao at job start. Requires Forgejo Runner v12.5.0+. If we adopt this, the OpenBao step in `pr-reviewer`'s `build-push.yaml` (and equivalents) gets a lot simpler — no more "fetch a service-account token, exchange it for a Bao token, exchange that for Harbor creds, write a docker config." The runner mints a JWT, exchanges with OpenBao directly via OIDC auth method, done. Adjacent work in OpenBao to add a JWT/OIDC auth role for the Forgejo issuer. ### New HTTP API for runner registration Forgejo 15.0 adds a proper HTTP API endpoint for runner registration and **deprecates** the old token-acquisition endpoints. The operator currently relies on the older flow (presumably). Migrate before the deprecated endpoints are removed in a future release. ## Medium-impact / hygiene - **Pin runner image to ≥ v12.5.0**: required for OIDC and `one-job`. Audit current pinned versions in runner pool definitions; bump as needed. - **Error handling: 403 → 404**: Forgejo now returns 404 (not 403) for resources the token can't see, to prevent enumeration. Any operator code that distinguishes "missing" from "forbidden" needs adjustment. - **Permission scope tightening**: template generation/deletion APIs and admin-level permissions on repo-specific tokens. Verify the operator's service token doesn't rely on now-removed admin scopes. ## Low-impact / informational - **Runner search by UUID** + new filter/visibility flags on runner list endpoints — useful for reconciliation logic when checking whether currently-registered runners match desired CR state. - **Multiple-tasks-per-fetch and job-specific runner requests** are runner-internal optimizations; nothing for the operator to wire up, but they shift the cost model in favor of larger pools / longer-lived runners staying interesting alongside ephemeral ones. - **Workflow-side changes** (reusable workflow expansion, dispatch input limit raised to 100, scheduled workflow timezone, etc.) — workflow authors' concern, not the operator's, but worth keeping in mind when documenting. ## Suggested ordering 1. Bump runner image version to 12.5.x in the existing pool definitions. Smallest blast radius; unblocks everything below. 2. Migrate registration to the new HTTP API. Pure plumbing change; preserves current architecture. 3. Add ephemeral runner mode as a new option on the `RunnerPool` CR (alongside the existing long-lived shape). 4. OIDC workload identity — design the OpenBao auth role first, then a workflow proof-of-concept (probably in `pr-reviewer` since it's the one with the most secret-handling), then expose via operator config.

rcsheets referenced this issue from a commit

2026-09-27 19:39:04 +00:00

feat: register runners through the Forgejo runner API, one Pod per runner

rcsheets referenced this issue

2026-09-27 19:39:40 +00:00

feat: register runners through the Forgejo runner API, one Pod per runner #55

rcsheets commented

2026-09-27 20:03:21 +00:00

Author

Owner

Progress: the "plumbing" half of this landed in v0.9.0 (#55). Target is current Forgejo (16.x, what git.brooktrails.org runs) and forgejo-runner (13.x) rather than a v15 floor; no compatibility with older Forgejo is kept.

Done

New HTTP registration API. The operator registers each runner itself (POST …/actions/runners) and keeps its uuid/token in a per-runner Secret; runners start with daemon --url --uuid --token-url. Deprecated registration-token endpoints, the register init container and .runner are gone.
Kubernetes pools: one Pod per runner (<pool>-n) instead of a Deployment, since the operator now owns each runner's identity. Existing pools migrate on first reconcile (legacy runners named <pool> deregistered, old Deployment/Secret/PVC removed).
Deregistration fixed — it had silently broken: the client used /admin/runners, which no longer exists. Now scope-aware (admin / org / repo) for list, get, delete.
403 → 404 handling: 404 is treated as "gone or not visible to this token".
Runner image ≥ v12.5: images and samples move to forgejo-runner 13 (the new flow needs ≥ v12.8.0 for --token-url; existing 12-latest images satisfy that).
Permission scope: tokens now only need runner-management rights in the pool's scope (site admin only for global pools).
Remote backend: VMs get operator-registered credentials; ephemeral: true VMs register a Forgejo ephemeral runner and run one-job.
Also along the way: Go toolchain 1.27; e2e runs against Forgejo 16 and asserts real registration.

Remaining

Ephemeral mode for Kubernetes pools — one Pod per queued job running one-job, registered as an ephemeral runner. Starting on the design now.
OIDC workload identity — nothing needed operator-side (the runner already passes ACTIONS_ID_TOKEN_REQUEST_* to jobs); the work is an OpenBao JWT/OIDC auth role for the Forgejo issuer, then a workflow proof-of-concept (probably pr-reviewer).
Runner search by UUID / visible flag: not needed so far; reconciliation keys on Forgejo runner IDs recorded when the operator registers.

🤖 Generated with Claude Code

Progress: the "plumbing" half of this landed in **v0.9.0** (#55). Target is current Forgejo (16.x, what git.brooktrails.org runs) and forgejo-runner (13.x) rather than a v15 floor; no compatibility with older Forgejo is kept. **Done** - [x] **New HTTP registration API.** The operator registers each runner itself (`POST …/actions/runners`) and keeps its uuid/token in a per-runner Secret; runners start with `daemon --url --uuid --token-url`. Deprecated registration-token endpoints, the `register` init container and `.runner` are gone. - [x] **Kubernetes pools: one Pod per runner** (`<pool>-n`) instead of a Deployment, since the operator now owns each runner's identity. Existing pools migrate on first reconcile (legacy runners named `<pool>` deregistered, old Deployment/Secret/PVC removed). - [x] **Deregistration fixed** — it had silently broken: the client used `/admin/runners`, which no longer exists. Now scope-aware (admin / org / repo) for list, get, delete. - [x] **403 → 404 handling**: 404 is treated as "gone or not visible to this token". - [x] **Runner image ≥ v12.5**: images and samples move to forgejo-runner 13 (the new flow needs ≥ v12.8.0 for `--token-url`; existing `12-latest` images satisfy that). - [x] **Permission scope**: tokens now only need runner-management rights in the pool's scope (site admin only for `global` pools). - [x] Remote backend: VMs get operator-registered credentials; `ephemeral: true` VMs register a Forgejo ephemeral runner and run `one-job`. - [x] Also along the way: Go toolchain 1.27; e2e runs against Forgejo 16 and asserts real registration. **Remaining** - [ ] **Ephemeral mode for Kubernetes pools** — one Pod per queued job running `one-job`, registered as an ephemeral runner. Starting on the design now. - [ ] **OIDC workload identity** — nothing needed operator-side (the runner already passes `ACTIONS_ID_TOKEN_REQUEST_*` to jobs); the work is an OpenBao JWT/OIDC auth role for the Forgejo issuer, then a workflow proof-of-concept (probably `pr-reviewer`). - Runner search by UUID / `visible` flag: not needed so far; reconciliation keys on Forgejo runner IDs recorded when the operator registers. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

rcsheets referenced this issue

2026-09-27 20:10:10 +00:00

fix: remote-backend scale-up relies on workflow_job webhooks, which Forgejo never sends #56

rcsheets referenced this issue from a commit

2026-09-28 01:12:38 +00:00

feat(kubernetes): ephemeral pools, one runner per job

rcsheets referenced this issue

2026-09-28 01:12:59 +00:00

feat(kubernetes): ephemeral pools, one runner per job #57