Headless CMS Migration Checklist
A safe CMS migration comes down to one rule: every URL that has rankings or links must resolve to the same content after launch, or 301-redirect to its new home. Most traffic loss in a migration is not caused by the new platform — it is caused by URLs that changed without redirects, metadata that got dropped, or a noindex left on from staging. The checklist below is ordered so SEO is protected at every step, not patched afterward.
Why migrations lose SEO
Search engines have spent months mapping your old URLs to their rankings. A migration that changes URL structure, alters page content, or breaks internal links forces a re-evaluation. Handled well, you keep your positions. Handled carelessly, you tell Google a thousand pages “disappeared” (404) and watch rankings fall for weeks. The redirect map is the single most important artifact in the whole project — build it first, not last.
The step-by-step migration checklist
- Crawl and inventory the old site first. Run a full crawl (Screaming Frog, Sitebulb, or equivalent) and export every indexable URL with its status code, title, meta description, H1, canonical, and word count. Pull the same URL list from your XML sitemaps and from Google Search Console’s Pages report. This snapshot is your source of truth — you cannot redirect URLs you never recorded.
- Content audit. Cross-reference the crawl with analytics and Search Console. Tag each URL: keep, merge, redirect, or retire. Pages with traffic, rankings, or backlinks are non-negotiable keeps. Thin or duplicate pages can be merged or retired — but retiring still needs a redirect to the nearest relevant page, never a bare 404.
- Map the new URL structure. Decide the new permalink scheme in the headless setup before migrating content. If you can keep URLs identical, do it — zero redirects is zero risk. Where they must change, document old-to-new as a 1:1 list.
- Build the 301 redirect map. For every changed URL, write a 301 (permanent) redirect from old to new. Use 301, not 302 — a 302 tells search engines the move is temporary and withholds ranking transfer. Avoid redirect chains (A→B→C); point every old URL directly at its final destination. Redirect to the equivalent page, never blanket-redirect everything to the homepage.
- Migrate content and preserve metadata. Move the body content and carry across the SEO fields that matter: title tags, meta descriptions, canonical tags, structured data (JSON-LD), image alt text, and Open Graph tags. In a headless build these become fields in your content model — model them explicitly so editors and the API both expose them.
- Rebuild internal links and navigation. Update internal links to point at final URLs, not through redirects. Recreate the menus, breadcrumbs, and contextual links that pass authority between pages. Broken or redirected internal links waste crawl budget and dilute link equity.
- Stage with indexing blocked. Build on a staging environment protected by HTTP auth or IP allowlist, and confirm
noindex/robots.txt Disallowis active there. Critically: confirm those blocks are removed on production before launch. A stagingnoindexshipped to production is the classic migration disaster. - Pre-launch crawl on staging. Crawl the staging build and diff it against the old-site inventory from step 1. Verify: every kept URL renders, titles and metadata are present, redirects resolve with a single 301, there are no unexpected 404s or 500s, canonicals are correct, and the XML sitemap lists the new URLs.
- Launch, then validate redirects live. Cut over, then immediately spot-check a sample of high-value redirects in production with
curl -Ior a crawler. Submit the new XML sitemap in Search Console and request indexing for the top pages. - Monitor for 4–8 weeks. Watch Search Console Coverage for spikes in 404s and “excluded” URLs, watch crawl stats, and track rankings and organic traffic against the pre-launch baseline. Fix any URL that surfaces as a 404 by adding its missing redirect.
Redirect status codes at a glance
| Code | Meaning | Use in a migration |
|---|---|---|
| 301 | Moved permanently | Default for every changed URL — transfers ranking signals |
| 302 | Found (temporary) | Avoid — withholds ranking transfer, signals a temporary move |
| 308 | Permanent redirect (preserves method) | Acceptable permanent alternative to 301 |
| 200 | OK | What a kept, unchanged URL should return |
| 404 | Not found | Acceptable only for genuinely retired pages with no equity |
| 410 | Gone | Use when you deliberately want a URL de-indexed |
Pre-launch gate (do not ship until all pass)
- Redirect map covers 100% of changed URLs from the step 1 inventory.
- No redirect chains — every old URL hits its final target in one hop.
- Staging
noindexandrobots.txtblocks confirmed removed on production. - Title, meta description, canonical, and structured data present on key pages.
- XML sitemap regenerated and pointing at final URLs.
- Internal links and navigation point at final URLs, not redirects.
What to watch after launch
Rankings often wobble for the first one to two weeks as search engines re-crawl and reconcile redirects — a short dip is normal and not a reason to revert. What is not normal is a rising count of 404s in Search Console or organic traffic that keeps falling past week three. Those point to missing redirects or dropped content, and both are fixable if you caught the baseline in step 1. Keep the old-site inventory until traffic has clearly stabilized.
If you are moving to a headless CMS and need the migration run so rankings hold — redirect map, content model, and staged cutover included — tell us about your project and we will plan the move end to end.
