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

First Migration Plan

Date: 2026-06-05

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.

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.

Do not add gitea-deploy in this phase.

Validation:

• Targets are read-only.
• Targets either succeed or fail with clear missing-tool messages.
• railiance-apps still owns deploy-capable Gitea targets during the transition.

Phase 3 - Deploy-Capable Target Review

Move deploy-capable Gitea ownership only after Phase 1 and Phase 2 are reviewed.

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 the Gitea token/remote creation issue is fixed.
• 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.

Open Blocker

The local tea login named coulomb is configured but currently fails with invalid username, password or token. This blocks creation of the remote coulomb/railiance-forge repository through the Gitea API.

Until refreshed credentials are available:

• keep railiance-forge local and State Hub-registered;
• do not add an origin remote that points to a missing repository;
• avoid claiming remote publication is complete.

Next Recommended Action

Proceed with Phase 1 documentation canonicalization after the operator confirms that compatibility pointers in railiance-apps are acceptable.