Transfer cluster repository to Personal organization with a GitOps-safe migration runbook #76
Labels
No labels
automation
automerge
ci
infra
migrated/beads
priority/P2
refactoring
repo-maintenance
status/in-progress
testing
type/epic
type/task
automerge
bug
dependencies
duplicate
help wanted
invalid
lang
rust
migrations
opencode
question
security
type
documentation
type
enhancement
type
maintenance
type
refactor
vulnerability
wontfix
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Reference
Personal/cluster#76
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Goal
Transfer the existing Forgejo repository from
martin/clusterto the confirmedPersonalorganization, resulting inPersonal/cluster, without interrupting GitOps reconciliation or losing repository history and issue tracking. Document a repeatable migration runbook and rollback procedure before executing the transfer.This issue schedules the work; creating it does not authorize performing the transfer or changing the live cluster.
Repository-specific context
modules/common.nixdefinesnetworking.clusterRepo = "https://code.${domain.root}/martin/cluster.git"and uses it fornixidy.target.repository; the target branch defaults tomain.env/dev/argocd.nixusesclusterRepofor Argo CD'srepositories.cluster.url.ssh://forgejo@nidaros.secure.martials.no/martin/cluster.git; distinguish this SSH endpoint from the HTTPS GitOps URL.networking.registryseparately points tocode.${domain.root}/martin. Repository transfer must not implicitly relocate container packages or break image pulls; assess package ownership separately.Required migration runbook
1. Inventory and preparation
Personal/clusterdoes not already exist. Preserve visibility, default branch, branch protections, collaborators, and bot access.sourceRepos, repository registrations, URL-scoped credential templates, external scripts, docs, badges, and local clones.https://code.martials.no/Personal/cluster.git, plus any applicable allowlists and credential registrations. Generate all affected manifests through Nixidy; never hand-edit generated YAML or encrypted SOPS files.just fmt,just test,just test-IT, and builds fordev,infra, andprod; review the generated diff for URL-only changes and unintended deletion/pruning, namespace, or application-identity changes. The user signs the commits.2. Controlled cutover
originto the new SSH path. Publish the complete source and generated manifests before enabling reconciliation against them.3. Verification and documentation
Personal/cluster.AGENTS.md, contributor/bootstrap docs, and external references to the new owner.Rollback and stop conditions
martinis permitted and whether the old namespace remains available before cutover. If reversing transfer, restore working repository access first, then revert canonical URLs/allowlists/credentials and regenerate manifests from the known-good Git state.Personal/clusterand roll back configuration there; do not restore a source URL that no longer hosts an accessible repository.Acceptance criteria
Personal/clusterwith history, issues, PRs, permissions, and protections verified.stagingenvironment and mismatched layout) #80Phase 1 (prep) complete — awaiting signed commit + transfer window
Prep changes are ready in the working tree for a local branch (
migration/personal-org), not yet committed (GPG signing is done by @martin).Changes
modules/common.nix:networking.clusterRepo→https://code.${domain.root}/Personal/cluster.git.networking.registrydeliberately unchanged (no app references it; images already publish tocode.martials.no/personal/<app>)..woodpecker/switch.yml: automerge endpoint now/api/v1/repos/${CI_REPO}/pulls/...instead of the hardcodedmartin/clusterpath.AGENTS.md: issue-tracking link/slug →Personal/cluster; new "Canonical Repository" subsection with the GitOps URL, the local SSH remote,git remote set-urlguidance, and the note that image pulls are independent of repo ownership.just switch {dev,infra,prod}— 11ApplicationrepoURLlines +manifests/dev/argocd/Secret-argocd-repo-cluster.yamlurl(decodes tohttps://code.martials.no/Personal/cluster.git). No other manifest churn: no deletions, no namespace/identity changes.Validation
just fmt— clean (0 files changed).just test— 108/108.just test-IT— 11/11.just diff {dev,infra,prod}reviewed before switching: only repoURL/url hunks.git grep martin/clusterover tracked files — no remaining references.Cluster inventory (verified live, not just Git)
Synced/Healthy, all sourcinghttps://code.martials.no/martin/cluster.git:apps-dev,apps-infra,apps-prod(roots, bootstrapped outside Git),argocd-dev(self-managed), plus 8 child apps.default) withsourceRepos: ['*']— no allowlist change required.argocd-repo-clusterSecret carries onlyurl+project; the repository is public, so Argo CD fetches anonymously and no credentials need rotating.2(forge_remote_id: 17); server runs withWOODPECKER_ORGS=Personal, so the new location matches existing policy.martin/*andPersonal/*(autodiscoverNamespaces: ["Personal"]) — no config change expected.flake-checkcron,pr-review, release) do not hardcode the repository slug.grafana-dashboardsdashboard link andbackstagesample catalog still reference the old slug (separate repos, follow-up commits).Follow-ups
stagingenvironment, layout) found during the inventory.Next: signed commit + PR (CI validates the build), then the cutover window (snapshot, pause root
syncPolicy, transfer, repoint live Applications, ordered sync, automation restore, verification).Cutover executed —
Personal/clusteris liveOwner transfer and merge were performed by @martin at ~20:13 UTC; the cluster was repointed immediately afterwards. No maintenance window pause was needed: no root
syncPolicywas suspended, and validation showed zero pruning.What was done
kubectl -n argocd get applications -o yaml→/tmp/argocd-apps-pre-repoint.yaml(5426 lines) before any changespec.source.repoURLpatched on all 14 Applications →https://code.martials.no/Personal/cluster.gitargocd-repo-clusterSecreturl→ new URL (also matches the regenerated manifest)git remote set-url origin ssh://forgejo@nidaros.secure.martials.no/Personal/cluster.git;git fetch --prune53840c0d4bc291(comment-only) rebase-merged; all apps refreshed onto itVerification evidence
git ls-remote ssh://…/martin/cluster.git→Forgejo: Cannot find repository. repo-server logged onestatus code: 301from the old HTTPS URL during the transition (GenerateManifest), so repointing was required rather than relying on the redirect. No such errors afterwards.Synced/Healthyatd4bc2913a55cdcf8ffaed6d5f74a280470b1fb51from the new URL:apps-dev,apps-infra,apps-prod,argocd-dev,argo-rollouts-infra,prometheus-stack-infra,martials.no-dev,martials.no-prod,recurring-events-dev,recurring-events-prod,sops-secrets-operator-dev,toolbox-dev,toolbox-prod,traefik-dev.status.operationState.syncResult.prunedlength is 0 for every application; resource counts unchanged (e.g.argocd-dev50,prometheus-stack-infra90,traefik-dev33).argocd-devreconciled itself from the new URL, and the resultingargocd-repo-clusterSecret keeps the new URL.Personal/clusteris public,mainremains default, 13 open issues (12 + #80) and 3 open PRs (#58, #44, #42) carried over, all 12 repository labels preserved.2(forge_remote_id: 17) re-registered asPersonal/cluster, active, default branchmain.345success; commit statusesci/woodpecker/pr/switchandci/woodpecker/pr/pr-reviewbothsuccess; branch head unchanged afterwards, i.e.nixidy switchproduced no manifest drift.systemctl start renovate.service→ autodiscovery reports 17 repositories includingPersonal/cluster; no config change needed because discovery already coveredPersonal/*.Residual items
345rangit add manifests/with nothing to commit, soclank-bot's push permission atPersonal/clusteris unproven. It will be exercised by the first manifest-affecting change; the criterion stays open until then.main— checked before (martin/cluster) and after (Personal/cluster):get_branch_protectionreturns "target couldn't be found" in both cases. Nothing was lost, but there is no protection or required status-check gate today.grafana-dashboards(dashboards/cluster-overview.jsonlink panel) andbackstage(examples/forgejo-repos.yamlsample catalog) — separate repositories.53840c0,G?=U); #82 used rebase and preserved the signed commit (d4bc291,G), though Forgejo reports "No principal matched" until the SSH signing key is registered on the profile.Documentation
AGENTS.mdgained the "Canonical Repository" section (GitOps URL, local SSH remote,git remote set-url, image-ownership note) and the issue-tracking link now points atPersonal/cluster— merged in #81.Closed — migration complete
Owner transfer, cutover, and verification are finished. Summary of the outcome:
Personal/clusteris the canonical GitOps repository;martin/clusterno longer exists and its SSH path does not resolve.https://code.martials.no/Personal/cluster.git,Synced/Healthy, with zero pruning across the move.networking.clusterRepoand the generated manifests point at the new owner;AGENTS.mddocuments the canonical GitOps URL and local remote.Personal/cluster(repo id2); PR pipeline, webhooks, and status checks verified at the new owner.Personal/cluster.Known exceptions accepted at closure:
clank-botpush access atPersonal/cluster.main: none existed before or after the transfer. Explicitly out of scope per @martin.grafana-dashboardsupdated in Personal/grafana-dashboards#9 (open, awaiting review/merge; nogcx resources pushrun).backstagecatalog refreshes automatically from the forge, so no change is needed.Follow-up left open: #80 (stale Getting Started docs).
Correction to the signature note above
My earlier statement that #81's squash merge landed "unsigned" was wrong.
53840c0is signed and Forgejo verifies it:And
d4bc291verifies as the user key (martin / SHA256:4p1Mo…). TheUI saw comes from localgit, not from Forgejo:~/.config/git/allowed_signersonly lists host SSH keys under thegit@martials.noprincipal, so instance-signed merges reportNo principal matched.The instance already signs merges via
[repository.signing](FORMAT = ssh,MERGES = always,SIGNING_KEY = /run/forgejo/id_ed25519.pub,SIGNING_NAME = Forgejo Instance), so no server-side key needs adding. The remaining work is local trust of that key, tracked in Personal/nixos-configuration#64.