pdurlej/platform

Fork 0

docs(forgejo): prepare W8.final upgrade preflight packet #508

New issue

Closed

opened 2026-05-26 17:54:23 +02:00 by codex · 1 comment

codex commented

2026-05-26 17:54:23 +02:00

Collaborator

Spec sources (whitelist)

state/cycle/W8-module-upgrade-prep.md §W8.final core/workbench / Stop Conditions
state/roadmap/forgejo-upgrade-plan.md
state/roadmap/current-platform-roadmap.md §09 - Module upgrade waves
modules/forgejo/module.yaml
modules/forgejo/runbook.md
decisions/0022-module-source-and-release-boundaries.md §Update workflow / Anti-patterns

Extracted context

From state/cycle/W8-module-upgrade-prep.md:

W8.final core/workbench: Upgrade Forgejo, Traefik, Infisical, Postgres, Redis, MinIO.
Forgejo last among workbench-critical services.

From state/cycle/W8-module-upgrade-prep.md stop conditions:

Stop W8 and ask the operator if any candidate touches Forgejo Actions/runners/packages before the Forgejo upgrade plan is accepted.

From modules/forgejo/module.yaml:

Forgejo hosts the platform repository and PR workflow, so an outage can slow fixes to Forgejo itself.

From decisions/0022-module-source-and-release-boundaries.md:

No production path should depend on a mutable tag alone. No production apply
should clone an arbitrary source repo and build during reconciliation.

Do NOT read (unless escape hatch fires)

Live Forgejo database/config on RS2000 — this issue is a preflight packet, not execution.
Forgejo admin UI settings — snapshot procedure may be described, but not performed here.
.forgejo/workflows/ — do not change workflows in this planning PR.
compose/ — no runtime wiring changes.

Allowed touched paths

state/cycle/W8-forgejo-final-preflight.md (create)
state/roadmap/forgejo-upgrade-plan.md (modify)
Optional: modules/forgejo/module.yaml (metadata/digest note only, if evidence is already present and no runtime change is implied)

Why this exists (product-first)

Forgejo is the workbench for the whole platform: issues, PRs, Actions, packages, and agent merge flow all depend on it. Its upgrade should be boring only after the pilot waves prove metadata, backup, registry, runner, and rollback mechanics.

Why this matters now

The operator wants to reach W8, but Forgejo must not be the first upgrade. A preflight packet lets us know exactly what evidence will be required later, without touching the runtime today.

What "done" looks like

A Forgejo W8.final preflight packet lists current version/image/digest, candidate discovery method, and release-note source.
Packet defines backup-before evidence for database, app data, packages, Actions/runners, and branch protection/settings snapshot.
Packet defines smoke checks: health endpoint, Actions dispatch/pickup, package registry push/pull, PR/review/merge path, and rollback.
Packet states explicit blockers and operator gate phrases for actual runtime execution.
No production upgrade, restart, compose change, or secret access is performed.

Scope

In scope:

Planning/preflight only for the later Forgejo upgrade.
Making the future operator approval checklist precise.

Out of scope:

Upgrading Forgejo.
Touching database/package storage.
Changing branch protection, runner config, Actions workflows, or registry permissions.
Using this issue as approval for any production mutation.

Suggested approach

Start from state/roadmap/forgejo-upgrade-plan.md.
Add missing evidence buckets discovered during W6d/Patchwarden work: review/approval path, package registry, Actions runner, branch protection snapshot.
Keep all execution steps as future gated checklist, not commands to run now.

Escape hatch

If the current plan is too stale or live Forgejo behavior must be inspected to make the packet truthful, stop and comment on #389 with the exact missing evidence.

Unknowns / owner questions

None for the preflight packet. Actual upgrade approval remains future operator gate.

Risk class

risk/runtime
risk/process
risk/exposure
risk/product

Class of service

class/security-sensitive

Trace

Original source: #389 W8 coordination lane after #501/#502
Migrated by: codex, 2026-05-26
Related issues / PRs: #389, #433, #501, #502, #503, #504

## Spec sources (whitelist) - `state/cycle/W8-module-upgrade-prep.md` §W8.final core/workbench / Stop Conditions - `state/roadmap/forgejo-upgrade-plan.md` - `state/roadmap/current-platform-roadmap.md` §09 - Module upgrade waves - `modules/forgejo/module.yaml` - `modules/forgejo/runbook.md` - `decisions/0022-module-source-and-release-boundaries.md` §Update workflow / Anti-patterns ## Extracted context > From `state/cycle/W8-module-upgrade-prep.md`: > ``` > W8.final core/workbench: Upgrade Forgejo, Traefik, Infisical, Postgres, Redis, MinIO. > Forgejo last among workbench-critical services. > ``` > > From `state/cycle/W8-module-upgrade-prep.md` stop conditions: > ``` > Stop W8 and ask the operator if any candidate touches Forgejo Actions/runners/packages before the Forgejo upgrade plan is accepted. > ``` > > From `modules/forgejo/module.yaml`: > ``` > Forgejo hosts the platform repository and PR workflow, so an outage can slow fixes to Forgejo itself. > ``` > > From `decisions/0022-module-source-and-release-boundaries.md`: > ``` > No production path should depend on a mutable tag alone. No production apply > should clone an arbitrary source repo and build during reconciliation. > ``` ## Do NOT read (unless escape hatch fires) - Live Forgejo database/config on RS2000 — this issue is a preflight packet, not execution. - Forgejo admin UI settings — snapshot procedure may be described, but not performed here. - `.forgejo/workflows/` — do not change workflows in this planning PR. - `compose/` — no runtime wiring changes. ## Allowed touched paths - `state/cycle/W8-forgejo-final-preflight.md` (create) - `state/roadmap/forgejo-upgrade-plan.md` (modify) - Optional: `modules/forgejo/module.yaml` (metadata/digest note only, if evidence is already present and no runtime change is implied) ## Why this exists (product-first) Forgejo is the workbench for the whole platform: issues, PRs, Actions, packages, and agent merge flow all depend on it. Its upgrade should be boring only after the pilot waves prove metadata, backup, registry, runner, and rollback mechanics. ## Why this matters now The operator wants to reach W8, but Forgejo must not be the first upgrade. A preflight packet lets us know exactly what evidence will be required later, without touching the runtime today. ## What "done" looks like - [ ] A Forgejo W8.final preflight packet lists current version/image/digest, candidate discovery method, and release-note source. - [ ] Packet defines backup-before evidence for database, app data, packages, Actions/runners, and branch protection/settings snapshot. - [ ] Packet defines smoke checks: health endpoint, Actions dispatch/pickup, package registry push/pull, PR/review/merge path, and rollback. - [ ] Packet states explicit blockers and operator gate phrases for actual runtime execution. - [ ] No production upgrade, restart, compose change, or secret access is performed. ## Scope **In scope:** - Planning/preflight only for the later Forgejo upgrade. - Making the future operator approval checklist precise. **Out of scope:** - Upgrading Forgejo. - Touching database/package storage. - Changing branch protection, runner config, Actions workflows, or registry permissions. - Using this issue as approval for any production mutation. ## Suggested approach 1. Start from `state/roadmap/forgejo-upgrade-plan.md`. 2. Add missing evidence buckets discovered during W6d/Patchwarden work: review/approval path, package registry, Actions runner, branch protection snapshot. 3. Keep all execution steps as future gated checklist, not commands to run now. ## Escape hatch If the current plan is too stale or live Forgejo behavior must be inspected to make the packet truthful, stop and comment on #389 with the exact missing evidence. ## Unknowns / owner questions - None for the preflight packet. Actual upgrade approval remains future operator gate. ## Risk class - [x] `risk/runtime` - [x] `risk/process` - [x] `risk/exposure` - [ ] `risk/product` ## Class of service - [x] `class/security-sensitive` ## Trace - Original source: #389 W8 coordination lane after #501/#502 - Migrated by: codex, 2026-05-26 - Related issues / PRs: #389, #433, #501, #502, #503, #504

codex added this to the 09 - Module upgrade waves milestone

2026-05-26 17:54:23 +02:00

codex added the

class/security-sensitive

labels

2026-05-26 17:54:23 +02:00

codex referenced this issue

2026-05-26 17:55:28 +02:00

meta(upgrades): plan staged module upgrade waves after metadata and DR #389

codex commented

2026-05-26 20:11:37 +02:00

Author

Collaborator

Sequencing note from codex: keep this proposed until #505/#506 land; then mark ready-for-agent as the next W8 batch. This is not blocked on more ADR/policy work, only on avoiding parallel drift while the first two packets establish current evidence.

codex referenced this issue from a pull request that will close it,

2026-05-26 22:30:19 +02:00

docs(forgejo): prepare W8 final preflight packet #512