Content Migration Dry Runs: A Practical Playbook for Safer CMS Moves

A CMS migration rarely fails because the export or import “did not run.” It fails because the result is subtly wrong: missing SEO fields, broken internal links, unexpected redirects, formatting drift, duplicated pages, or “published” content that should have stayed in draft.

A dry run is a rehearsal: you run the migration end to end in a controlled environment, measure outcomes against expectations, fix the migration process, and repeat until the output is boringly predictable. The goal is not perfection in one attempt. The goal is repeatability and evidence.

This playbook focuses on practical steps small and mid-sized teams can use, whether you are moving from one traditional CMS to another, adopting headless, or consolidating multiple sites.

Why dry runs matter for CMS migrations

Content has structure, behavior, and downstream consumers. Editors see a page. Search engines see metadata. Sales teams share URLs. Support links to help articles. A migration changes the plumbing that all of those rely on.

Dry runs reduce risk in three ways:

• They reveal hidden requirements. You discover rules that lived in someone’s head, like “Every product page must have a canonical URL and a default category.”
• They quantify scope. Instead of “a lot of pages,” you learn “12,438 items, 1.7% missing hero text, 84 broken internal links.”
• They create a rollback mindset. Rehearsals force you to plan the moment you realize something is wrong and need to stop.

Without dry runs, the first full end-to-end test happens during the real cutover, when time pressure is highest and your options are worst.

Define the migration contract (what must stay true)

Before you build tooling, write a migration contract. This is a short list of “must be true after the move” statements that you can test. Think of it as acceptance criteria for content, not for code.

What belongs in the contract

• Identity: every migrated item has a stable identifier (legacy ID stored somewhere) so you can trace issues back to the source.
• URLs: URL patterns for key content types are preserved or redirected 1:1.
• Status rules: drafts stay drafts, scheduled content stays scheduled, and archived content is not accidentally published.
• Required fields: required fields remain present (title, slug, language, primary category, etc.).
• SEO invariants: meta title/description, canonical URLs, and robots directives map predictably.
• Relationships: references (author, category, related products) either migrate correctly or fail loudly.

Then translate the contract into a field mapping document. It can be as simple as a table that lists source field, destination field, transform notes, and whether it is required.

If you only do one thing, do this: decide what the migration should do when it cannot satisfy the contract. Should it block the item, create a placeholder, or stop the run? Defaulting to “silently drop” is how migrations produce long-tail bugs.

{
  "contentType": "Article",
  "identity": "legacy_id",
  "urlRule": "/blog/{slug}/",
  "requiredFields": ["title","slug","body","status","updated_at"],
  "mappings": [
    {"from":"seo.meta_title","to":"seoTitle","required":false},
    {"from":"author.name","to":"byline","required":true}
  ],
  "onViolation": "quarantine"
}

Build a repeatable dry-run environment

A good rehearsal environment is not just “a staging site.” It is a place where you can run the same migration multiple times and compare results.

Practical guidelines:

• Freeze inputs: take a snapshot export from the legacy CMS and treat it as the rehearsal dataset. If the source keeps changing, your measurements will not mean much.
• Reset the destination: every dry run starts from a clean destination dataset, or a known baseline. If you cannot reset, you will chase duplicates and false failures.
• Separate secrets and permissions: use service accounts with only the access needed for migration, and keep them distinct from production.
• Log with correlation IDs: every migrated item should produce a log line that includes legacy ID and new ID. When an editor reports “this page looks wrong,” you should locate its migration path quickly.

Also choose a simple naming scheme for each run, like dryrun-01, dryrun-02. That makes it easier to store results (reports, diff summaries, known issues) and prevents teams from arguing about which run “counted.”

Validate content like a product, not a dataset

Validation is where migrations become safe. You need checks that reflect how the site is used: by editors, by readers, and by systems like search and analytics.

Three layers of validation

1. Schema validation: do items fit the destination model? Are required fields present? Are field types correct?
2. Behavior validation: does the site render correctly? Do redirects work? Are internal links still valid?
3. Expectation validation: are counts and distributions sane? For example, “number of published articles by year” should not collapse to zero.

Keep validation evidence lightweight but consistent. A simple approach is to produce one report per dry run:

• Total items migrated per content type, plus failed and quarantined counts
• Top 20 validation errors, grouped by rule
• URL redirect coverage: how many legacy URLs map to a destination URL
• A small set of sampled pages for editorial review

Concrete example: imagine a regional retailer migrating from a plugin-heavy CMS to a structured CMS. In dry run 1, they migrate 8,200 product pages but discover 640 products have empty “shipping details” because the legacy site stored that text in a reusable block. Without a rehearsal, that would have shipped as blank content. With a dry run, they add a transform rule to expand reusable blocks, then re-run and watch the error count drop close to zero.

Validation should not be only automated. Include a short editor review cycle where content owners check a small but representative set: top landing pages, evergreen help docs, and content with complex formatting.

A checklist for each rehearsal

Copy this checklist and treat it as the “definition of done” for a dry run. Each item produces an artifact you can share with stakeholders.

• Inputs frozen: legacy export snapshot named and stored (what data did we migrate?).
• Destination reset: clean baseline confirmed (what did we start from?).
• Run configuration recorded: mapping version, transform rules, and run ID (what process did we use?).
• Counts captured: items by type, by status, by locale (what moved?).
• Violations handled: quarantined items list exported with reasons (what failed and why?).
• Redirect plan tested: sample of old URLs verified to reach correct new pages (what breaks externally?).
• Media check: representative media files render and have expected dimensions/alt text where applicable (what breaks visually?).
• Editorial spot check: at least 10 to 20 high-impact pages reviewed and signed off (does it read correctly?).
• Diff summary: what changed since last dry run and what is still open (are we converging?).

Common mistakes (and how to avoid them)

Most migration pain comes from a few predictable patterns. If you recognize them early, you can redesign the process before cutover.

• Measuring success by “number of items imported.” Avoid this by tracking quarantined items, missing required fields, and broken URLs. Volume is not correctness.
• Skipping legacy ID retention. Always store the legacy ID in the destination. Otherwise, you cannot reconcile reports or handle edge cases efficiently.
• Letting editors find problems informally. Give editors a short, intentional review list. Unstructured review turns into random browsing and missed issues.
• Assuming rich text will “just work.” Formatting, embeds, and custom shortcodes often require transforms. Identify these early using samples from your most complex pages.
• Overlooking drafts and scheduled content. Teams test only published pages. Then cutover accidentally publishes drafts or drops scheduled launches.

A helpful discipline is to treat every bug found during validation as a new rule: either a mapping adjustment, a transform, or a contract decision (block, quarantine, or default).

When not to do a full dry run

Dry runs are usually worth it, but not always at full scale. Here are cases where a smaller rehearsal is more appropriate:

• Very small sites: if you have 30 pages and no complex relationships, a manual move with a strict checklist may be safer than building migration tooling.
• Content redesign projects: if the destination information architecture is fundamentally different, you may need a “content inventory and rebuild” approach, not a direct migration.
• Constantly changing source: if the old CMS cannot be stabilized and content changes daily, focus on incremental sync rehearsals (small batches) rather than repeated full resets.

Even in these cases, do at least one rehearsal on a representative subset. A “pilot migration” often catches the same classes of problems with less overhead.

Conclusion

A safe CMS migration is less about heroics on launch day and more about calm, repeated rehearsal. Define what “correct” means, run the process in a resettable environment, validate outcomes in layers, and keep artifacts that make progress visible.

When your final cutover feels like “dry run 5, but in production,” you have done the hard part already.

FAQ

How many dry runs should we plan for?

Plan for at least two: one to reveal unknowns and one to prove the fixes. Many teams land around three to five runs if the site has multiple content types, redirects, and media.

What should we do with items that fail validation?

Quarantine them into a clearly labeled list with reasons and legacy IDs. Decide per content type whether failures block launch, get fixed manually, or can be deferred without harming readers.

Do we need a perfect redirect map before the first rehearsal?

No. Start with your highest-value URLs and a general rule for the rest. Each dry run should expand redirect coverage and reveal edge cases like duplicated slugs or old URL patterns.

How do we keep editor review manageable?

Use a curated sample: top pages by business importance, a few pages from each content type, and pages with complex formatting. Rotate samples between dry runs so you cover breadth without overwhelming reviewers.