Migration Rehearsal dry-run
The Migration Rehearsal at /governance/rehearsal runs the full pre-flight logic of a real migration — permission resolution, content type lookup, version enumeration, page rendering, user mapping — without writing a byte to the destination. The output is a verdict report you walk through with the client for written sign-off before cutover.
Example verdict from a marketing-hub rehearsal. Your verdict depends on scope and mapping coverage.
WHAT YOU'LL SEE
A verdict pill on top — Green / Amber / Red — then the blockers/warnings/info cells and a plan-coverage grid of what is in scope. Every finding is deep-linkable into the site/library it came from, and each has a resolution column that doubles as your pre-cutover punch list.
Before you start
- Source credential with Site Collection Reader or higher on every site in scope.
- Destination credential with write access matching the real migration. The rehearsal authenticates and performs a
HEADagainst the destination to catch bad tokens or missing permissions before cutover. - User mapping CSV (required for cross-tenant, optional for same-tenant). Two columns, header row:
sourceUpn,destUpn alice@old-tenant.com,alice@new-tenant.com bob@old-tenant.com,robert.jones@new-tenant.com
UPNs are case-insensitive. BlankdestUpn= intentionally unmapped; those permissions are dropped silently rather than flagged broken. - Licensing. Included on every paid migration plan and on Partner+ governance tiers. Free: up to 3 rehearsals per tenant.
Running the rehearsal
- Open Governance → Migration Rehearsal (
/governance/rehearsal).BreadcrumbGovernance › Migration Rehearsal › New rehearsal - Pick source and destination credentials.
Source:sp-old-tenant-readerDestination:sp-new-tenant-admin
- Choose scope to match the real job: Single site, Multiple sites, or Hub.
Single site Hub (marketing) Multiple sites
- Configure options (see below). Match these to the real job's options — a rehearsal with Migrate permissions off tells you nothing about permission migration.
✓Migrate permissions ✓Migrate content types ✓Migrate views ✓Migrate versions ✓Migrate pages ✓True History Mode
- Upload the user mapping CSV if applicable.
Uploaduser-mapping-northridge.csv · 415 rows · ✓ parsed
- Click Run rehearsal. Typical runtime: 10–30% of the real migration since no bytes move.
Run rehearsalResolving principals on site 4 / 7…
TIP
Mirror the real job's options exactly. A "green" rehearsal with Migrate versions unchecked will absolutely not predict behaviour on a real run that has versioning on — the version-cap flags never had a chance to fire.
Options checkboxes
| Option | What the rehearsal validates |
|---|---|
| Migrate permissions | Every unique principal on every securable item is resolved against the destination tenant via the mapping CSV. Unmapped principals are flagged. |
| Migrate content types | Every source content type is looked up at the destination hub. Missing content types are flagged with the destination GUID that would need to be provisioned. |
| Migrate views | CAML query compatibility check against the destination list schema. Views referencing source-only columns are flagged. |
| Migrate versions | Version history is enumerated and the count / size-on-disk projection is added to the report. Flags libraries whose version cap is lower at the destination. |
| Migrate pages | Modern pages are rendered in shadow mode and every web part is checked for a destination-side equivalent. Classic pages are flagged with their modernization target (see the Modernization scan). |
| True History Mode | Re-writes Author / Editor / Created / Modified at the destination to match the source exactly, using the mapping CSV to resolve the original UPNs. The rehearsal validates that every historical editor resolves — a former employee whose account is gone will surface here, not on cutover night. |
Reading the report
Each site gets a verdict pill at the top of its section:
- Green — "Ready to migrate". Zero blockers. Warnings (if any) are informational and the real migration will succeed without intervention.
- Amber — "Ready with warnings". The migration will succeed but with acknowledged trade-offs — e.g., 3 unmapped UPNs whose permissions will be dropped, or a content type that will fall back to the parent. Print the warnings section and walk the client through it for explicit sign-off.
- Red — "Blockers present". One or more issues will fail the real migration. Do not schedule cutover until every red item is resolved.
Every finding has a resolution column with the exact action: "Add row to mapping CSV", "Provision content type at destination hub", "Enable versioning on destination library", etc. The PDF export preserves this column — it doubles as a punch list for the pre-cutover sprint.
Client sign-off
Export as PDF (Export → PDF). The PDF includes verdict summary, full finding list, mapping coverage (X of Y source UPNs mapped), and a signature block.
Suggested sign-off clause
"Client acknowledges the warnings in sections X, Y, Z of the attached rehearsal report dated <date>, accepts the identified behaviour post-migration, and authorizes MigrationFox to proceed with cutover on <cutover date>."
A signed rehearsal is the single most effective way to avoid post-migration scope arguments — almost every "that wasn't in scope" conversation traces back to a warning that would have been on page 2 of a rehearsal that was never run.
Troubleshooting
Every user flagged unmapped
BOM or encoding issue on the CSV. Re-save as UTF-8 without BOM, or use the built-in editor at Governance → User Mappings.
"Destination hub unreachable"
Destination credential lacks Sites.FullControl.All or Sites.Manage.All. Grant it, or use a tenant-admin credential.
Green rehearsal, failed migration
Almost always configuration drift between rehearsal and cutover (deleted content type, edited mapping CSV). Re-run the rehearsal within 24 hours of cutover.
DON'T
Never schedule cutover from a red rehearsal assuming "we'll fix it during the window." Blockers fail at a point where rollback is painful and the client is watching. Clear every red item first, re-run, then schedule.
What's next
- SharePoint Site Migration — execute the migration once the rehearsal is green.
- Dependency Graph scan — identify which Power Apps / flows need rebinding post-cutover.
- Share a migration live view with your client — give the client a read-only window into the real job.
- Permission migration overview — how UPN mapping and True History Mode interact.