
Editorial illustration; the environments shown are conceptual.
A Drupal configuration import can enable a module, change a field, alter a view or remove configuration that no longer exists in the sync directory. That makes drush config:import a deployment step, not a harmless file copy. A quick review of what will change can prevent a surprise on production.
This workflow is for teams using Drupal’s configuration synchronization between copies of the same site. It focuses on reviewing and rehearsing the import; exact commands and deployment order should match the versions of Drupal and Drush in your project.
Summary
- Confirm the source and destination are the intended environments and share the expected site UUID.
- Review added, changed and deleted configuration before importing; investigate every unexpected deletion.
- Check module code, dependencies, content impact and environment-specific settings alongside the YAML diff.
- Back up the destination, rehearse the import and verify the user-facing features afterward.
What the import is going to change
Drupal keeps active configuration in the database and can export it as YAML into a synchronization directory. The import makes active configuration match that exported set. Drupal’s configuration management guide explains that configuration includes items such as enabled modules, content types, fields, vocabularies and views. The destination site UUID is used to confirm that the sync set belongs to the same site.
The important operational detail is that a full import can include removals as well as additions and changes. A deleted view or field may be intentional, but an unexpected deletion deserves investigation before production.
Preflight: inspect the change set
1. Confirm the deployment context
Check the repository branch, deployed code version, database environment and configured sync directory. Confirm you are connected to staging or production as intended. A command that is correct in one environment can be harmful in another if the shell points to the wrong site.
Check the site UUID on source and destination where appropriate. Drupal’s docs note that configuration synchronization is intended between copies of the same site; do not work around a mismatch by casually editing the UUID. A mismatch may mean you have the wrong site or a flawed deployment process.
2. Ask Drupal to show the pending changes
From the project root, a common Drush review is:
drush config:status
drush config:import --diff
Command options can vary with Drush versions, so check drush help config:import for your installed release. In the UI, the Configuration Synchronization page also shows differences and allows review before an import. The point is to inspect the actual change set before accepting it.
Look for:
- New or removed configuration files.
- Changes to fields, form displays, permissions, views, menus or workflows.
- Module configuration whose code is missing from the deployed release.
- Changes that refer to a content entity or vocabulary that does not exist at the destination.
- Environment-specific values that should come from settings overrides rather than shared sync YAML.
A large change set is not automatically wrong. But if a routine text edit suddenly proposes dozens of unrelated changes, stop and find out why configuration was exported from a different state.
3. Match configuration to code and content
Configuration does not deploy missing module code by itself. Ensure composer-managed modules and themes required by the new config are included and deployed in the same release. Check the order of database updates and configuration import against your project’s documented release process.
Configuration can also reference content that differs between environments. A view may depend on a field or taxonomy term; a menu link may point to a route supplied by a module. Test those dependencies on staging with representative content, especially if production editors have created content since the last deployment.
4. Separate shared config from environment settings
Database credentials, API secrets and environment-specific service URLs should not be treated like ordinary shared configuration. Drupal supports settings overrides in settings.php; use the project’s established method to keep local and production values distinct. Review config changes for hostnames, email destinations, analytics identifiers, payment modes and integrations before importing.
Do not add a new contributed module just to ignore a configuration difference without understanding the trade-off. If production editors are allowed to change a particular setting, document who owns it and how deployments will preserve or reconcile it.
5. Back up and rehearse
Take a database backup before a production synchronization, and ensure the release can be rolled back according to your team’s procedure. Import into staging first using the same code and configuration artifact intended for production. Run the project’s database updates and cache rebuild steps in its documented order; Drush guidance describes common deployment commands, but the correct sequence can depend on the application and release.
After the staging import, inspect logs and test the changed feature. A green command exit status tells you the import completed, not that the resulting editorial workflow is correct.
Example: a field disappears from the import diff
Suppose a feature branch removes a field from a content type. The diff may also remove its form display, view display and field storage configuration. Before accepting the deletion, ask whether content still uses the field and whether the feature change includes the data migration or retirement plan. A configuration import can remove the field definition; it does not automatically answer what the business wants done with existing values.
If the change is meant to retire the field, document that decision and verify the content outcome on staging. If the deletion was accidental, restore the expected config in the source, export again and review the new diff.
Common mistakes
- Importing from an unknown working tree. Verify the checked-out commit and sync directory.
- Ignoring deletions. Removed config can represent a real site behavior change.
- Deploying YAML without required module code. The import and code release need to agree.
- Assuming config includes content. Content entities and configuration are different deployment concerns.
- Treating successful import as user acceptance. Open the changed forms, pages and permissions afterward.
Our Drupal configuration management guide covers how the synchronization model works. For a specific content deployment, the Drupal migration rehearsal workflow describes how to test a migration separately from configuration changes.
Why this matters
Drupal configuration is executable site behavior expressed as data. Reviewing the difference before import catches wrong-environment deployments, unintended removals and missing dependencies while recovery is still straightforward.
My Take
I treat a config diff like a code review: every surprising line needs an explanation. That habit is faster than debugging an unexplained production change after editors report that a form or page has vanished.
Bottom Line
Verify the environment, inspect additions, changes and deletions, confirm code and content dependencies, then rehearse and back up before production. Finish by testing the specific feature the import was meant to change.