diff --git a/docs/changelog.d/upgrade-forgejo-runner.doc.md b/docs/changelog.d/upgrade-forgejo-runner.doc.md new file mode 100644 index 0000000..e4f904b --- /dev/null +++ b/docs/changelog.d/upgrade-forgejo-runner.doc.md @@ -0,0 +1 @@ +Add Mikado chain for upgrading k8s forgejo-runner from v6.3.1 to v12.x diff --git a/docs/how-to/forgejo-runner/review-runner-config-v12.md b/docs/how-to/forgejo-runner/review-runner-config-v12.md new file mode 100644 index 0000000..96a5ca7 --- /dev/null +++ b/docs/how-to/forgejo-runner/review-runner-config-v12.md @@ -0,0 +1,60 @@ +--- +title: Review Runner Config for v12 +status: active +modified: 2026-02-22 +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. + +## Background + +The runner config in `argocd/manifests/forgejo-runner/configmap.yaml` was written for v6.3.1. Six major versions may have introduced new config keys, changed defaults, or deprecated options. + +## Current Config + +```yaml +log: + level: info +runner: + file: /data/.runner + capacity: 2 + timeout: 3h + envs: + DOCKER_HOST: tcp://127.0.0.1:2375 + TZ: America/Los_Angeles +container: + network: "host" + docker_host: tcp://127.0.0.1:2375 +``` + +## Steps + +1. Fetch the v12.7.0 example config: + ```fish + curl -L "https://code.forgejo.org/forgejo/runner/raw/tag/v12.7.0/.forgejo-runner.example.yaml" + ``` +2. Diff against our current config — note new sections/keys +3. Check the release notes for each major version (v7–v12) for config-related changes: + - v7.0: `FORGEJO_*` env vars (backward compat with `GITHUB_*`) + - v8.0: Default container image change + - v12.7: `server.connections` for multi-server polling; secret URLs; ephemeral mode +4. Decide which new keys to adopt (if any) and update the ConfigMap +5. Pay attention to `container.valid_volumes` and `container.options` (added in v6.x for security) — we may want to configure these + +## Key Areas to Check + +- **`container.valid_volumes`** — allowlist for volume mounts in job containers (security hardening from v6.x) +- **`container.options`** — allowlist for container options +- **`runner.envs`** — are `FORGEJO_*` vars needed alongside `GITHUB_*`? +- **Ephemeral mode** (v12.7) — one-shot runners that de-register after a job. Not needed now but worth noting. +- **`server.connections`** — multi-server polling. Not needed (single Forgejo instance). + +## Related + +- [[upgrade-k8s-runner]] — Parent goal diff --git a/docs/how-to/forgejo-runner/upgrade-k8s-runner.md b/docs/how-to/forgejo-runner/upgrade-k8s-runner.md new file mode 100644 index 0000000..d549597 --- /dev/null +++ b/docs/how-to/forgejo-runner/upgrade-k8s-runner.md @@ -0,0 +1,55 @@ +--- +title: Upgrade K8s Forgejo Runner to v12 +status: active +requires: + - validate-workflows-against-v12 + - review-runner-config-v12 +modified: 2026-02-22 +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/configmap.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-workflows-against-v12.md new file mode 100644 index 0000000..7cf168f --- /dev/null +++ b/docs/how-to/forgejo-runner/validate-workflows-against-v12.md @@ -0,0 +1,79 @@ +--- +title: Validate Workflows Against v12 +status: active +modified: 2026-02-22 +tags: + - how-to + - forgejo-runner + - ci +--- + +# Validate Workflows Against v12 + +Run `forgejo-runner validate` (available from v9.0+) against all workflow files to catch schema issues before upgrading the k8s runner daemon. + +## Background + +Forgejo-runner v8.0 introduced workflow schema validation — workflows that don't pass are rejected at runtime. v9.0 made this stricter and added a `validate` CLI command. Since we're jumping from v6.3.1, we've never run validation. All six workflows in `.forgejo/workflows/` need checking. + +## Approach + +### Option A: Run validate locally + +Download the v12.7.0 binary for darwin-arm64 and run it against the workflow files: + +```fish +# Download the runner binary +curl -L -o /tmp/forgejo-runner \ + "https://code.forgejo.org/forgejo/runner/releases/download/v12.7.0/forgejo-runner-12.7.0-darwin-arm64" +chmod +x /tmp/forgejo-runner + +# Validate each workflow +for f in .forgejo/workflows/*.yaml + /tmp/forgejo-runner validate $f +end +``` + +### Option B: Run in a container on indri + +```fish +ssh indri 'docker run --rm -v /path/to/repo/.forgejo:/workspace \ + code.forgejo.org/forgejo/runner:12.7.0 \ + forgejo-runner validate /workspace/workflows/' +``` + +### Option C: Add a CI validation step + +Add a pre-flight workflow or mise task that runs `forgejo-runner validate` against all workflow files. This could become a permanent guardrail — see "Future: Automated Validation" below. + +## Workflows to Validate + +| File | Complexity | Notes | +|------|-----------|-------| +| `build-container.yaml` | High | Matrix strategy, conditional steps | +| `build-container-nix.yaml` | High | Matrix strategy, conditional steps | +| `build-blumeops.yaml` | High | Multi-step release pipeline | +| `deploy-fly.yaml` | Low | Simple deploy | +| `cv-deploy.yaml` | Medium | Version resolution + deploy | +| `branch-cleanup.yaml` | Low | Scheduled + manual dispatch | + +## Fix any failures + +If validation fails, fix the workflow schema issues in the same PR as the runner upgrade. Common issues in the v8/v9 changelog: +- Invalid `type:` values in `workflow_dispatch.inputs` +- Incorrect `if:` expression syntax +- Undeclared or misspelled keys + +## Future: Automated Validation + +Consider adding a mise task or CI step that validates workflows on every push. This would catch schema regressions before they reach the runner. Options: + +1. **Mise task** (`mise run validate-workflows`) that downloads/caches the runner binary and runs `validate` +2. **Pre-commit hook** using the runner binary +3. **CI workflow** that validates other workflows (circular but useful) + +Document whichever approach is chosen when this card is completed. + +## Related + +- [[upgrade-k8s-runner]] — Parent goal diff --git a/docs/how-to/how-to.md b/docs/how-to/how-to.md index c96c6aa..f548277 100644 --- a/docs/how-to/how-to.md +++ b/docs/how-to/how-to.md @@ -93,3 +93,11 @@ Mikado chain for deploying Authentik. Track progress with `mise run docs-mikado - [[provision-authentik-database]] - [[create-authentik-secrets]] - [[migrate-grafana-to-authentik]] + +## Forgejo Runner + +Mikado chain for upgrading the k8s forgejo-runner daemon from v6.3.1 to v12.x. Track progress with `mise run docs-mikado upgrade-k8s-runner`. + +- [[upgrade-k8s-runner]] +- [[validate-workflows-against-v12]] +- [[review-runner-config-v12]]