Running Migrations

Requires Node.js 18 or later.

Do not use npx contentful-migration as a CLI command. The migration CLI command is in contentful-cli, and should be run via npx contentful ....

You need a Content Management API (CMA) access token with write access to the target space.

Create it in one of these places:

• Account settings -> CMA tokens: https://app.contentful.com/account/profile/cma_tokens
• Space-scoped CMA tokens page: https://app.contentful.com/spaces/<SPACE_ID>/api/cma_tokens

CLI Usage (Contentful CLI)

Flags

Examples

Environment Variables

Where to find each value:

• CONTENTFUL_SPACE_ID: in the Contentful URL (/spaces/<SPACE_ID>/...) or Space settings -> API keys.
• CONTENTFUL_MANAGEMENT_ACCESS_TOKEN: Account settings -> CMA tokens (https://app.contentful.com/account/profile/cma_tokens) or https://app.contentful.com/spaces/<SPACE_ID>/api/cma_tokens.
• CONTENTFUL_ENVIRONMENT_ID: Space settings -> Environments (for example master, sandbox, staging).

If any required value is missing, ask the user to populate it in .env before running migrations.

Programmatic API

Use runMigration() to run migrations from Node.js scripts, test runners, or CI pipelines.

Install the library for programmatic usage:

Options

Environment Strategy

Never run untested migrations directly against your production environment.

Recommended workflow:

1. Create a sandbox environment from master (via the Contentful web app or CMA).

2. Run migrations against sandbox:

   bashCopy

   npx contentful space migration -s abc123 -e sandbox --management-token "$CMA_TOKEN" 001-create-blog.ts

3. Verify the content model and entries look correct in the web app.

4. Run against master (or your production environment alias):

   bashCopy

   npx contentful space migration -s abc123 -e master --management-token "$CMA_TOKEN" 001-create-blog.ts

5. Delete the sandbox when done (via the web app or CMA).

For teams using environment aliases, point your production alias to the migrated environment rather than running migrations against the aliased environment directly.

Migration File Organization

Name migration files with sequential prefixes so they run in order:

Guidelines:

• One logical change per file
• Use descriptive names that explain what the migration does
• Keep the numbering sequential with zero-padded prefixes
• Commit migration files to version control
• Never edit a migration that has already been applied — write a new one instead

Testing Migrations

1. Sandbox environments are the primary testing mechanism. Create one, run the migration, verify, delete.

2. Dry-run approach: Use context.makeRequest to read current state, log what would change, and return early:

   typescriptCopy

   import type { MigrationFunction } from 'contentful-migration'
   
   const migration: MigrationFunction = async (migration, { makeRequest }) => {
     const types = await makeRequest({ method: 'GET', url: '/content_types' })
     console.log('Would affect:', types.items.map((t: any) => t.sys.id))
     return
   }
   
   export = migration

3. Programmatic tests: Use runMigration() in your test suite against a dedicated test environment.

CI/CD Integration

Run migrations as part of your deployment pipeline:

This script reads CONTENTFUL_MANAGEMENT_ACCESS_TOKEN from your shell environment and passes it to --management-token.

Track which migrations have been applied (e.g., in a version entry or external state file) to avoid re-running completed migrations.