Add Mikado chain for k8s forgejo-runner upgrade (v6.3.1 → v12.x)

C2 change: three cards documenting the upgrade path, breaking changes,
and prerequisites (workflow validation, config review).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

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

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

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

docs/how-to/forgejo-runner/validate-workflows-against-v12.md

@@ -0,0 +1,82 @@
+---
+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: Dagger Pipeline
+
+Add a `validate_workflows` function to the [[dagger]] module (`.dagger/src/blumeops_ci/main.py`). This runs `forgejo-runner validate` inside the upstream runner container — no host-side binary management, reproducible, and version-pinned.
+
+```python
+@function
+async def validate_workflows(
+    self,
+    src: dagger.Directory,
+    runner_version: str = "12.7.0",
+) -> str:
+    """Validate Forgejo Actions workflow files against runner schema."""
+    return await (
+        dag.container()
+        .from_(f"code.forgejo.org/forgejo/runner:{runner_version}")
+        .with_directory("/workspace", src)
+        .with_workdir("/workspace")
+        .with_exec([
+            "sh", "-c",
+            "for f in .forgejo/workflows/*.yaml; do "
+            '  echo "=== $f ===" && forgejo-runner validate "$f"; '
+            "done"
+        ])
+        .stdout()
+    )
+```
+
+Invoke locally with:
+
+```fish
+dagger call validate-workflows --src=.
+```
+
+### Permanent guardrail
+
+Once the function exists, wire it into CI as a pre-commit hook or a mise task (`mise run validate-workflows`). This prevents future workflow regressions regardless of runner version changes. The `runner_version` parameter lets us pin to whatever version the k8s runner is actually running.
+
+## 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
+
+## Deliverables
+
+1. `validate_workflows` function in `.dagger/src/blumeops_ci/main.py`
+2. All 6 workflows passing validation (fix any schema issues)
+3. A mise task or pre-commit hook wiring `dagger call validate-workflows` for ongoing use
+
+## Related
+
+- [[upgrade-k8s-runner]] — Parent goal

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]]