Reference checklist: moving repos into an org / rebuilding a project board

[PBNZ]

Retrospective finding — refs #10 (post-retrospective addendum: multi-repo migration, day 2).

Context

Executing a live "personal account → organization" migration (repo transfer + rename, org project board rebuilt from scratch, CI re-homed) hit six platform landmines in one afternoon. Each is a verified GitHub platform fact, each cost a debugging loop, and none is written down anywhere in the standard. A migration checklist would have converted all six into non-events.

The six, with symptom → cause:

1. Replacing a Project's status options breaks the default workflows silently. Rebuilding the Status field (new column set via API) leaves every built-in workflow ("item closed → status X", "auto-close", "PR merged") pointing at deleted option ids — they show a warning icon and dangle until each is re-edited by hand in the UI.
2. A fresh org's Actions policy can default to local-only. First CI run after transfer dies with startup_failure (no logs, "workflow file issue") because actions/checkout etc. are org-blocked. Fix: org Settings → Actions → allow GitHub-authored actions (tightest sufficient option).
3. The Projects API does not follow repo-transfer redirects. Item-add calls with pre-transfer issue URLs fail with "resource not found" even though the same URLs redirect fine in a browser. Rewrite URLs to the new owner/name before scripting board moves.
4. Built-in project auto-add is per-repo and plan-capped (1 workflow on Free, 5 on Pro/Team — each targeting a single repo). A multi-repo board on Free gets exactly one auto-added repo; the rest is manual/agent adds or per-repo Actions workflows.
5. Environment protection rules on private repos need Pro (personal) or Team (org). On a Free org the "required reviewer" deploy gate silently doesn't exist — design the human gate around something else (e.g. the release-publish act) until the plan changes.
6. Transfer before creating Actions secrets and Environments. Sequencing the transfer first means there is nothing sensitive to lose or leak in the move; GitHub keeps issues/PRs/labels and redirects old URLs (git + web — but not the Projects API, see 3).

Also worth a line: startup-failed workflow runs cannot be re-run — trigger a fresh run instead.

Tasks

• Add a migration reference/checklist doc, ordered by phase: before transfer (6), board rebuild (1, 4), after transfer (2, 3, 5), each item as symptom → cause → fix.
• Cite GitHub docs for the plan-dependent facts (4, 5) so future readers re-verify against current limits.

Acceptance criteria

• The checklist exists; someone running the same migration cold hits zero of the six.

— 🤖 Claude, on behalf of @PBNZ

[PBNZ]

Triage: accepted.

Landed on PR #18 (commit 8349761): standard/org-migration-checklist.md — the six landmines phased before transfer (transfer-first sequencing, plan the deploy gate) / after transfer (org Actions policy startup_failure, startup-failed runs can't be re-run, Projects API doesn't follow transfer redirects) / board rebuild (status-option replacement dangles the built-in workflows, auto-add caps), each as symptom → cause → fix.

Per the acceptance criteria, the plan-dependent facts were re-verified against current GitHub docs today and cited inline: auto-add workflows cap at 1 (Free) / 5 (Pro & Team) / 20 (Enterprise), each targeting a single repo; environment configuration on private repos needs Pro (personal) or Team (org), and public→private conversion drops existing protection rules and environment secrets. The Projects-API redirect gap isn't in the docs, so it's marked as observed platform behaviour. The doc also cross-references the closing-force rules (#15) when re-enabling board automations.

— 🤖 Claude, on behalf of @PBNZ

[PBNZ]

Verified on main (f7ab31c): standard/org-migration-checklist.md — six landmines phased as symptom → cause → fix, plan-dependent limits cited to current GitHub docs (re-verified 2026-07-20). Closing on @PBNZ's instruction.

— 🤖 Claude, on behalf of @PBNZ