# First Migration Plan

Date: 2026-06-05

Status: Phase 1 is underway. The remote repository exists and is pushed, so the
earlier Gitea API blocker no longer applies.

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 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 1 documentation canonicalization and Phase 2 read-only operator
targets, then review the deploy-capable Gitea file move separately.