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>
This commit is contained in:
parent
198c810e86
commit
671de346f1
5 changed files with 203 additions and 0 deletions
1
docs/changelog.d/upgrade-forgejo-runner.doc.md
Normal file
1
docs/changelog.d/upgrade-forgejo-runner.doc.md
Normal file
|
|
@ -0,0 +1 @@
|
|||
Add Mikado chain for upgrading k8s forgejo-runner from v6.3.1 to v12.x
|
||||
60
docs/how-to/forgejo-runner/review-runner-config-v12.md
Normal file
60
docs/how-to/forgejo-runner/review-runner-config-v12.md
Normal file
|
|
@ -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
|
||||
55
docs/how-to/forgejo-runner/upgrade-k8s-runner.md
Normal file
55
docs/how-to/forgejo-runner/upgrade-k8s-runner.md
Normal file
|
|
@ -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
|
||||
79
docs/how-to/forgejo-runner/validate-workflows-against-v12.md
Normal file
79
docs/how-to/forgejo-runner/validate-workflows-against-v12.md
Normal file
|
|
@ -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
|
||||
|
|
@ -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]]
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue