seeded repo

docs/first-migration-plan.md

@@ -0,0 +1,130 @@
+# 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.