From 030daf286ba05a8c953b46206568d0a2dcc96117 Mon Sep 17 00:00:00 2001 From: Erich Blume Date: Mon, 20 Apr 2026 08:15:25 -0700 Subject: [PATCH] docs: consolidate forgejo-runner how-tos --- ...o-runner-v12-8-server-connections.infra.md | 1 + .../forgejo-runner/configure-k8s-runner.md | 100 ++++++++++++++++++ .../review-runner-config-v12.md | 39 ------- .../forgejo-runner/upgrade-k8s-runner.md | 52 --------- ...t-v12.md => validate-forgejo-workflows.md} | 15 ++- 5 files changed, 108 insertions(+), 99 deletions(-) create mode 100644 docs/changelog.d/forgejo-runner-v12-8-server-connections.infra.md create mode 100644 docs/how-to/forgejo-runner/configure-k8s-runner.md delete mode 100644 docs/how-to/forgejo-runner/review-runner-config-v12.md delete mode 100644 docs/how-to/forgejo-runner/upgrade-k8s-runner.md rename docs/how-to/forgejo-runner/{validate-workflows-against-v12.md => validate-forgejo-workflows.md} (61%) diff --git a/docs/changelog.d/forgejo-runner-v12-8-server-connections.infra.md b/docs/changelog.d/forgejo-runner-v12-8-server-connections.infra.md new file mode 100644 index 0000000..aa64b6c --- /dev/null +++ b/docs/changelog.d/forgejo-runner-v12-8-server-connections.infra.md @@ -0,0 +1 @@ +Consolidated Forgejo runner how-to documentation into two cards covering declarative `server.connections` configuration and workflow validation, removing stale one-off upgrade notes. diff --git a/docs/how-to/forgejo-runner/configure-k8s-runner.md b/docs/how-to/forgejo-runner/configure-k8s-runner.md new file mode 100644 index 0000000..3c095d0 --- /dev/null +++ b/docs/how-to/forgejo-runner/configure-k8s-runner.md @@ -0,0 +1,100 @@ +--- +title: Configure K8s Forgejo Runner +modified: 2026-04-20 +last-reviewed: 2026-04-20 +tags: + - how-to + - forgejo-runner + - ci +--- + +# Configure K8s Forgejo Runner + +Configure the Kubernetes Forgejo runner on [[indri]] using declarative `server.connections` config instead of first-boot `register`. + +## Why This Flow + +The older bootstrap pattern used `forgejo-runner register` on container start and persisted `/data/.runner` in an `emptyDir`. That works, but it depends on deprecated CLI flows and mutates runner identity at runtime. + +The preferred pattern is: + +- Create runner credentials once on the Forgejo host +- Store the runner UUID and token in 1Password +- Inject them into Kubernetes via [[external-secrets]] +- Render `server.connections` in `argocd/manifests/forgejo-runner/config.yaml` + +This keeps runner identity under secret management and makes pod restarts idempotent. + +## Create Runner Credentials + +On [[indri]], use Forgejo's local CLI instead of the web UI: + +```bash +ssh indri 'cd ~/code/3rd/forgejo && ./forgejo forgejo-cli actions register \ + --name k8s-runner \ + --scope instance \ + --secret "$(openssl rand -hex 32)"' +``` + +This returns a runner UUID. The generated secret becomes the runner token. Store both in 1Password under the "Forgejo Secrets" item as: + +- `runner_k8s_uuid` +- `runner_k8s_token` + +## Kubernetes Secret Wiring + +Expose those fields with `argocd/manifests/forgejo-runner/external-secret.yaml` and make them available to the runner container as environment variables. + +The deployment should not carry registration-only env vars like `FORGEJO_URL`, `RUNNER_NAME`, or `RUNNER_TOKEN`. + +## Runner Config + +Keep the runner configuration in `argocd/manifests/forgejo-runner/config.yaml`. The key change is adopting `server.connections`: + +```yaml +server: + connections: + forgejo: + url: https://forge.ops.eblu.me + uuid: ${FORGEJO_RUNNER_UUID} + token: ${FORGEJO_RUNNER_TOKEN} + labels: + - k8s:docker://registry.ops.eblu.me/blumeops/runner-job-image: +``` + +Other settings that still matter for this deployment: + +- `runner.capacity: 2` +- `runner.timeout: 3h` +- `runner.shutdown_timeout: 3h` +- `container.network: host` +- `container.docker_host: tcp://127.0.0.1:2375` + +We do not currently use cache configuration, extra volume mounts, or multiple Forgejo connections. + +## Deployment Shape + +The pod still runs two containers: + +1. `runner` — Forgejo runner daemon +2. `dind` — Docker-in-Docker sidecar + +The startup script only needs to wait for DinD and then launch the daemon. It should no longer call `forgejo-runner register` or depend on `/data/.runner`. + +## Upgrade Procedure + +When bumping the runner version: + +1. Update `VERSION` in `containers/forgejo-runner/container.py` +2. Review release notes for runner breaking changes +3. Confirm `config.yaml` is still compatible with the current runner defaults +4. Build and release the updated `forgejo-runner` image +5. Update `argocd/manifests/forgejo-runner/kustomization.yaml` to the new image tag +6. Validate workflows with [[validate-forgejo-workflows]] +7. Sync the `forgejo-runner` ArgoCD app and trigger a test workflow + +## Related + +- [[validate-forgejo-workflows]] — Validate workflow schema against the deployed runner line +- [[forgejo-runner]] — Service reference +- [[build-container-image]] — Build and release the runner image diff --git a/docs/how-to/forgejo-runner/review-runner-config-v12.md b/docs/how-to/forgejo-runner/review-runner-config-v12.md deleted file mode 100644 index af50090..0000000 --- a/docs/how-to/forgejo-runner/review-runner-config-v12.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Review Runner Config for v12 -modified: 2026-02-27 -last-reviewed: 2026-02-27 -tags: - - how-to - - forgejo-runner - - ci ---- - -# Review Runner Config for v12 - -Compare the current runner ConfigMap against the v12.7.0 default config to identify new, changed, or deprecated keys. - -## Findings - -Compared `forgejo-runner generate-config` output from v6.3.1 and v12.7.0. Our config is minimal and remains valid for v12. - -### New sections in v12 (not adopted) - -- **`server.connections`** — multi-server polling. Not needed (single Forgejo instance). -- **`cache.secret_url`** — load cache secret from file URL. Not needed. -- **`runner.report_retry`** — retry config for log uploads. Defaults are fine. - -### Changed semantics - -- **`container.docker_host`** — v12 supports `unix://` and `ssh://` URLs. Our explicit `tcp://127.0.0.1:2375` still correct for DinD sidecar. -- **`cache`** section restructured with proxy/server split and better docs. We don't configure cache, so defaults apply. - -### Config update applied - -Added `shutdown_timeout: 3h` to allow graceful job completion on pod termination (v12 default, was missing from our v6 config). Added review date comment. - -`container.valid_volumes` and `container.options` left empty — our jobs use host networking and don't mount volumes. Can harden later if needed. - -## Related - -- [[upgrade-k8s-runner]] — Parent goal -- [[validate-workflows-against-v12]] — Sibling prerequisite diff --git a/docs/how-to/forgejo-runner/upgrade-k8s-runner.md b/docs/how-to/forgejo-runner/upgrade-k8s-runner.md deleted file mode 100644 index 3d285ac..0000000 --- a/docs/how-to/forgejo-runner/upgrade-k8s-runner.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Upgrade K8s Forgejo Runner to v12 -modified: 2026-02-27 -last-reviewed: 2026-02-27 -tags: - - how-to - - forgejo-runner - - ci ---- - -# Upgrade K8s Forgejo Runner to v12 - -Upgrade the k8s forgejo-runner daemon from v6.3.1 to v12.7.0 (or latest v12.x at time of execution). - -## Background - -The k8s runner on indri (minikube) uses the upstream `code.forgejo.org/forgejo/runner` image, currently pinned to v6.3.1. The latest is v12.7.0. The runner is still in alpha and uses major version bumps for each breaking change, so v6→v12 crosses six major versions. The ringtail runner is already at ~v12.6.4 via nixpkgs and needs no work. - -Blast radius is low — if the upgrade breaks CI, revert the image tag in `argocd/manifests/forgejo-runner/deployment.yaml` and sync. - -## Breaking Changes Crossed - -| Version | Change | Impact | -|---------|--------|--------| -| v7.0 | CLI `--gitea-instance` → `--forgejo-instance`; `FORGEJO_*` env vars | Low — our registration doesn't use the old flag | -| v8.0 | Workflow schema validation; default image → `node:22-bookworm` | Workflows must pass validation | -| v9.0 | Stricter schema + actions validation; `forgejo-runner validate` added | Same — but now we have a tool | -| v10.0 | Cache isolation; skip v10.0.0 (regression) | Low | -| v11.0 | License MIT → GPLv3 | Non-technical | -| v12.0 | Git binary required; git worktrees for remote actions | Low — OCI image includes git | - -## Execution Steps - -Once prerequisites are met: - -1. Update `argocd/manifests/forgejo-runner/deployment.yaml`: - - Change runner image from `code.forgejo.org/forgejo/runner:6.3.1` to `code.forgejo.org/forgejo/runner:12.7.0` -2. Update `argocd/manifests/forgejo-runner/config.yaml` with any config changes from [[review-runner-config-v12]] -3. Push, sync ArgoCD: `argocd app sync forgejo-runner` -4. Verify runner registers and connects: check Forgejo admin → runners -5. Trigger a test workflow (manual dispatch of `build-container.yaml` or `branch-cleanup.yaml`) -6. Update `service-versions.yaml` to note the daemon version - -## Rollback - -Revert the image tag to `6.3.1` in `deployment.yaml`, push, and sync. - -## Related - -- [[forgejo]] — Forgejo service reference -- [[validate-workflows-against-v12]] — Pre-upgrade workflow validation -- [[review-runner-config-v12]] — Config format review diff --git a/docs/how-to/forgejo-runner/validate-workflows-against-v12.md b/docs/how-to/forgejo-runner/validate-forgejo-workflows.md similarity index 61% rename from docs/how-to/forgejo-runner/validate-workflows-against-v12.md rename to docs/how-to/forgejo-runner/validate-forgejo-workflows.md index 5f98502..ed21de7 100644 --- a/docs/how-to/forgejo-runner/validate-workflows-against-v12.md +++ b/docs/how-to/forgejo-runner/validate-forgejo-workflows.md @@ -1,20 +1,20 @@ --- -title: Validate Workflows Against v12 +title: Validate Forgejo Workflows modified: 2026-04-11 -last-reviewed: 2026-02-27 +last-reviewed: 2026-04-20 tags: - how-to - forgejo-runner - ci --- -# Validate Workflows Against v12 +# Validate Forgejo Workflows -Run `forgejo-runner validate` (available from v9.0+) against all workflow files to catch schema issues before upgrading the k8s runner daemon. +Run `forgejo-runner validate` against all workflow files to catch schema issues before upgrading the k8s runner daemon. ## Result -All 6 workflows pass v12.7.0 schema validation with no changes needed: +All current workflows pass the validation step with no changes needed: - `branch-cleanup.yaml` — OK - `build-blumeops.yaml` — OK @@ -27,7 +27,7 @@ All 6 workflows pass v12.7.0 schema validation with no changes needed: 1. `validate_workflows` function added to `src/blumeops/main.py` (formerly `.dagger/src/blumeops_ci/main.py`) - Uses `forgejo-runner validate --directory .` inside the upstream runner container - - `runner_version` parameter (default `12.7.0`) pins to deployed version + - `runner_version` parameter pins validation to the deployed runner line 2. `mise run validate-workflows` task wired to `dagger call validate-workflows` 3. Pre-commit hook triggers on `.forgejo/workflows/` changes @@ -41,5 +41,4 @@ dagger call validate-workflows --src=. ## Related -- [[upgrade-k8s-runner]] — Parent goal -- [[review-runner-config-v12]] — Sibling prerequisite +- [[configure-k8s-runner]] — Runner configuration and upgrade flow