Keep Drupal Configuration in Sync Across Environments Without Wiping Production Changes

The problem: a production tweak that disappears on the next deploy

An administrator edits a view display directly on the production site to fix an urgent issue. Two weeks later, a developer deploys a new content type from staging. The deployment runs drush config-import, and the production view change is gone. This happens because Drupal's Configuration Synchronization treats the active configuration directory as the source of truth. Changes made in the production admin UI live in the database until they are exported; an import overwrites them with whatever is in version control.

The useful takeaway is to treat configuration like code: export from one environment, review the diff, import into another, and never edit production configuration by hand in the admin UI unless you plan to export and redeploy it.

What Drupal configuration actually means

Drupal core stores site configuration—content types, views, fields, and system settings—as YAML files in the active configuration directory. This is separate from content, which lives in the database. Nodes, users, and uploaded files are not moved by configuration synchronization.

Configuration Split is a contributed module that lets you filter configuration into separate directories. A common use case is enabling development-only modules, such as Devel, on local sites while keeping them out of production.

Review before you import

Run these commands from the Drupal project root, typically as a deployment user with read access to the database and write access to the configuration directory. Avoid running as root unless your deployment requires it.

1. Check for drift:

drush config-status

Expected result: a list of configuration entities and whether they are in sync. If the list is empty, the active configuration matches the sync directory.

1. Preview changes:

drush config-diff

Expected result: a YAML diff showing what would change during import. Review this before committing anything to version control. Missing required modules or incompatible schema versions can cause the diff or the import to fail.

Worked example: importing a content type change

Assume a developer has exported configuration from staging into /var/www/example/config-export.

# Run on the target environment, such as production
drush config-import --source=/var/www/example/config-export

Required permissions: the user must be able to connect to the Drupal database and write to the active configuration directory. Risk: an import can trigger entity schema updates and may put the site into maintenance mode automatically. If a required module is missing, the import can fail partway through and leave configuration partially updated.

After the command finishes, clear caches:

drush cache-rebuild

Handle environment-specific settings separately

Use Configuration Split to keep environment-specific configuration out of the shared sync directory. For example, you can split development modules into a config/development directory that is only active locally. Production imports then skip those modules entirely. Do not store API keys or other secrets in plain YAML; use settings.php overrides or encrypted environment variables instead.

Limitations and how to verify the result

• Configuration synchronization does not move content. A new content type may import successfully, but nodes of that type still need to be migrated or created separately.
• Hand-edited YAML on production can break the import due to syntax errors or missing dependencies.
• Configuration changes made in the production admin UI are lost on the next import unless they are exported and redeployed.

Practical check: after an import, run drush config-status again. The out-of-sync list should be empty for the imported items. Then open the affected admin page—for example, the content type or view you changed—and confirm the settings are present. Clear caches and test the feature before removing maintenance mode.

Rollback if the import causes problems

Because config-import changes site state, have a rollback plan before running it:

• Take a database backup before importing.
• If the import fails or causes errors, revert the configuration YAML in version control and run drush config-import again, or restore the database backup.
• Test the import first on a clone of production in staging so you can catch missing modules or schema mismatches without affecting live users.

Configuration management works best when the sync directory is treated as the single source of truth. Export changes from the environment where they were made, review the diff, import into the target environment, and verify with config-status before declaring the deploy complete.