docs: consolidate forgejo-runner how-tos

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.

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:<tag>
+```
+
+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

docs/how-to/forgejo-runner/review-runner-config-v12.md

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

docs/how-to/forgejo-runner/upgrade-k8s-runner.md

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

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
+- [[configure-k8s-runner]] — Runner configuration and upgrade flow
-- [[review-runner-config-v12]] — Sibling prerequisite