---
title: Repository Renames — Operator Reference
---

# Repository renames

State Hub preserves repository history across a Forgejo name change by keeping
the repository UUID and Forge numeric ID unchanged. The new slug becomes
canonical and the former slug remains a protected alias.

The dashboard is a read surface. Execute and recover renames with the
`statehub repo rename` CLI and the repository-owned migration workplan.

## What to inspect here

After the `statehub-rebound` phase:

1. Open `/repos/<old-slug>`. An amber banner must identify the requested slug
   as an alias and link to the canonical repository page.
2. Open `/repos/<new-slug>`. Both pages must report the same repository UUID;
   the canonical page lists the old alias.
3. Review workplans/tasks, dispatch, token totals, SBOM, services,
   capabilities, inbox, interface changes, and stale external references.
4. Treat stale Fabric or external projections as owner handoffs. Their source
   is not silently rewritten by State Hub.

Matching dashboard counts are useful but insufficient. Final verification uses
the per-record relationship checksums returned by:

```text
statehub repo rename verify <operation-id> --json
```

## Read the achieved phase

```text
statehub repo rename status <operation-id> --json
```

The `phase` is the last durable achievement. An `error_code` describes the last
failed attempt and does not advance the phase. Follow `next_safe_action`; reuse
the same operation UUID for retries.

| Phase | Next normal action |
| --- | --- |
| `preflighted` | Apply `forge-renamed`. |
| `forge-renamed` | Apply `statehub-rebound`; never register a replacement repository. |
| `statehub-rebound` | Verify/register a fresh canonical clone, then apply `source-synced`. |
| `source-synced` | Collect owner handoff evidence and apply `consumers-verified`. |
| `consumers-verified` | Re-run verification and apply `completed`. |
| `completed` | Soak, hand off residuals, then request cleanup approval. |
| `rollback-preflight` | Review blockers and irreversible effects before `--execute`. |
| `rolled-back` | Verify old canonical routes and affected consumers. |

## Safety boundaries

- Repository rename approval does not rename products, packages, APIs,
  namespaces, environment variables, policies, or telemetry labels.
- Forgejo credentials stay in their approved custodian; they never enter State
  Hub commands or evidence.
- External repositories own and close their own file-backed handoff tasks.
- Rollback does not undo consumer commits, deployments, published artifacts,
  external caches, or historical telemetry.
- The old checkout is removed last, after terminal verification, soak, live
  residual handoffs, and explicit path-specific approval.
- The protected old alias remains. Alias retirement is a separate decision.

The complete source runbook is `docs/repository-rename-operations.md`; its
versioned handoff contract is
`docs/schemas/repository-rename-handoff-v1.schema.json`.
