railiance-forge/docs/first-migration-plan.md

First Migration Plan

Date: 2026-06-05

Status: Phases 1 through 3 are complete as file ownership moves. No live Helm deploy, SOPS decryption, or Kubernetes apply was run.

This plan starts the extraction of forge ownership from railiance-apps into railiance-forge without changing the live Gitea deployment.

The rule for the first migration is simple: move knowledge and read-only operator entry points before moving deploy-capable configuration. That sequence has now been followed.

Goals

• Make railiance-forge the canonical place to look for forge and registry operation.
• Keep railiance-apps usable for current S5 app operators during transition.
• Preserve all secret boundaries; do not decrypt or copy live secret values.
• Avoid any Helm release or Kubernetes apply during the first migration.
• Keep future Forgejo cutover separate from current Gitea ownership transfer.

Non-Goals

• No live Gitea upgrade.
• No Forgejo deployment or cutover.
• No registry retention cleanup.
• No Actions runner deployment.
• No app release changes.
• No SOPS decryption.

Phase 1 - Documentation Canonicalization

Move registry operation knowledge first.

Steps:

1. Copy railiance-apps/docs/gitea-container-registry.md to railiance-forge/docs/gitea-container-registry.md.
2. Copy railiance-apps/docs/gitea-package-registry.md to railiance-forge/docs/gitea-package-registry.md.
3. Replace the originals in railiance-apps with short compatibility pointers to the new canonical files.
4. Update railiance-apps/docs/vergabe-teilnahme.md and other app docs to refer to forge-owned registry docs.

Validation:

• git diff --check in both repos.
• No commands require Gitea credentials.
• No live cluster changes.

Phase 2 - Read-Only Operator Targets

Add forge-side operator entry points that inspect current state before owning deployment.

Initial railiance-forge/Makefile targets:

• gitea-status: current Gitea pod, service, ingress, and gitea-db consumer status, copied/adapted from railiance-apps.
• registry-docs: print canonical docs to inspect.
• check-tools: minimal local tool check for kubectl, helm, sops, and optional tea.

gitea-deploy was intentionally deferred until Phase 3.

Validation:

• Targets are read-only.
• Targets either succeed or fail with clear missing-tool messages.
• railiance-apps still has compatibility wrappers during the transition.

Phase 3 - Deploy-Capable Target Review

Move deploy-capable Gitea ownership only after Phase 1 and Phase 2 are reviewed. This is now complete as a file move.

Candidate moves:

• helm/gitea-values.sops.yaml;
• helm/gitea-registry-values.yaml;
• manifests/gitea-ingress.yaml;
• make gitea-deploy;
• make gitea-ingress-deploy.

Review gates:

• railiance-forge remote exists and is pushed.
• State Hub workplans are synced in both repos.
• Operator confirms deploy-capable Gitea ownership should move now.
• railiance-apps has compatibility pointers for old paths.
• The plan distinguishes current Gitea operation from future Forgejo cutover.

Validation:

• helm template or dry-run equivalent can render from the new path without decrypting secrets into Git.
• No decrypted SOPS material appears in diffs.
• Existing live service stays untouched until an explicit deploy command is run.

Phase 4 - S5 Scope Cleanup

After deploy-capable assets move, update railiance-apps:

• remove long-term Gitea ownership language from SCOPE.md;
• keep app release and app runbook ownership;
• keep app registry consumption references;
• update RAILIANCE-WP-0005 to split Gitea package storage posture into forge-owned work;
• keep app database and app backup handoffs in S5/platform coordination.

Validation:

• railiance-apps no longer claims forge runtime ownership.
• App operators can still find registry instructions through pointers.

Remote Status

railiance-forge now has origin configured as gitea-remote:coulomb/railiance-forge.git and the local main branch is aligned with origin/main.

Next Recommended Action

Complete Phase 4 S5 scope cleanup and decide when compatibility wrappers in railiance-apps can be retired.