
Editorial illustration; the screen is representative and is not a real Drupal installation.
Every Drupal developer eventually hits the same painful moment: you deploy a routine code update to production, and five minutes later a client asks why the filter they added to a View last week vanished. Nothing broke in PHP—someone edited a View directly in the production admin UI, nobody exported it to Git, and the deployment’s configuration import dutifully reverted the database to match the repository.
Drupal stores active configuration in the database for speed, while its Configuration Management system lets you serialize that state into YAML files. Treating those YAML files as deployable code—reviewed in pull requests alongside PHP and Twig—is the difference between predictable releases and guessing what changed on a live site.
Separating configuration from content
Before touching any export command, be clear on what belongs in Git and what belongs in the editorial database. A new Article node is content; adding a field_subtitle field to the Article content type is configuration. Taxonomy terms created by editors are usually content, whereas the vocabulary itself and its URL alias pattern are configuration. A View’s filters, fields, and display settings are configuration, while the nodes it lists are content.
Blurring this line causes two classic problems. If you treat configuration as database-only, structural changes stay trapped on one server. Conversely, if you expect a configuration import to move blocks or menu links that Drupal treats as content entities, your staging test will look fine while production ends up with broken references.
Keeping the sync directory and secrets clean
Check where your project stores exported YAML before running commands. In a standard Composer-based Drupal 10 or 11 project with web/ as the docroot, settings.php should point the sync directory outside the web root:
$settings['config_sync_directory'] = '../config/sync';
Never place config/sync inside web/sites/default/files/ or any publicly reachable folder, because those YAML files expose role permissions, module lists, and site structure.
Just as important: keep API keys, SMTP credentials, and local development modules out of config/sync. Use $config overrides in settings.php (reading from environment variables) or a module like Config Split so local tools such as devel or stage_file_proxy stay active on your laptop without ever being enabled on production.
A reliable export, review, and import cycle
Start from a clean local or staging environment synced from a recent production database snapshot so your baseline matches reality. Make one focused change in the UI—for instance, adding a field, adjusting a role permission, or updating a View—rather than bundling a dozen unrelated tweaks together.
Export the active configuration and inspect the diff right away:
drush cex -y
git status
git diff config/sync/
Reading the YAML diff is where most mistakes are caught. An accidental click in the Views UI or an unintended permission checkbox shows up clearly in Git. You will also spot if core.extension.yml changed unexpectedly because a module was enabled or disabled. If the configuration depends on a custom module, formatter, or hook_update_N(), commit the YAML in the exact same commit or PR as the PHP code.
When deploying to staging first (and later to production), take a database backup, then follow Drupal’s standard deployment order:
drush sql:dump --gzip --result-file=../backups/pre-deploy.sql
drush updb -y
drush cim -y
drush cr
Running drush updb before drush cim ensures schema updates and new module hooks exist before configuration tries to reference them. Many teams wrap this sequence in drush deploy, which runs database updates, config import, cache rebuild, and deploy hooks in one consistent pass. Before importing, you can also run drush cst (config:status) on the target environment to verify whether someone made undocumented edits directly on production.
Failure modes that catch small teams off guard
Undocumented production hotfixes: If an emergency forced someone to edit a setting directly on production, do not overwrite it blindly. Run drush cst to see what drifted, export those changes on a temporary branch or recreate them locally, and merge them into config/sync before the next release.
Site UUID mismatches: Importing configuration exported from one site into an unrelated database fails with a UUID error because Drupal checks system.site.yml to prevent wiping the wrong site. Always build staging and local environments from a copy of the production database rather than running a separate fresh install and trying to force-import config across different UUIDs.
Assuming config/sync is a backup: YAML files describe how the site is wired, not user uploads, nodes, or commerce orders. Keep separate database and sites/default/files backups, and test a restore periodically instead of discovering a corrupted dump during an outage.
For related guides that complement this workflow, see:
- Drupal Layout Builder Is Powerful—But It Needs a Clear Content Model
- Drupal Cron Is Quietly Doing Important Work: How to Operate It Reliably
- Drupal Views: When the Module Helps, When It Adds Complexity, and How to Start
Configuration management does not eliminate human judgment, especially when a diff touches permissions or access rules. What it gives you is visibility: every structural change has a diff, a commit message, and a predictable path from your laptop to production.