Drupal Configuration Management: Config Sync, settings.php and Safe Deployments

Drupal keeps your site's structure in configuration and your site's text in content, and almost every deployment problem people have comes from not knowing which of the two they just changed.

Get that split clear and the rest of Drupal's management story falls into place: what belongs in git, what does not, what a deployment consists of, and why the same change behaves differently on staging and production.

Configuration versus content, precisely

Configuration is the shape of the site — content types, fields, view modes, Views, text formats, roles and permissions, blocks, menus as structures, theme settings. It is developer-owned and it belongs in version control.

Content is what people put in the shape — nodes, taxonomy terms, users, files, media, block content entities. It is editor-owned and it lives only in the database.

The boundary catches people out in two places. A menu is configuration; the links inside it are content entities. A block placement is configuration; the content block it displays is content. When a change works locally and vanishes on production, this is nearly always why.

Where configuration actually lives

Configuration is stored in the database while the site runs, and exports to YAML files on disk. The export location is a setting, not a fixed path: $settings['config_sync_directory'], declared in settings.php. Core reads it in core/lib/Drupal/Core/Config/FileStorageFactory.php and throws an exception if it is not defined, so this is not optional on a site you intend to deploy.

Put it outside the web root. The commented example in Drupal's own default.settings.php shows exactly that, and the reason is straightforward — those YAML files describe your permission structure and nobody outside your team should be able to fetch them.

The deployment loop

Once configuration is in files, a deployment is four steps in a fixed order, and the order matters:

1. Pull the new code.
2. Install dependencies with Composer.
3. Run database updates.
4. Import configuration.

Database updates before configuration import, every time. An update hook may create the thing your configuration refers to, and importing first produces an error that names the wrong culprit. Finish with a cache rebuild.

The workflow that goes with it: change configuration in your local environment, export it, commit the resulting YAML, review the diff in the pull request, and import on the target. Never make a configuration change directly on production. The next import will overwrite it, silently, and nobody will connect the two events.

Environment-specific values

Some settings must differ between environments — a development-mode flag, an API endpoint, a cache lifetime. Configuration files are shared across all environments, so those values do not belong in them.

Use the $config override array in settings.php instead. Drupal's own documentation for it carries a warning worth repeating: overridden values are not visible in the administration interface, which shows the stored configuration rather than the active override. Someone will eventually change a setting in the UI, see no effect, and lose an afternoon. Write the overrides down somewhere your team reads.

Two contributed modules exist for larger cases — one to split configuration per environment, one to exclude specific items from import. Neither is in core. Reach for them when the $config array genuinely stops scaling, not before.

What to check before you trust your setup

• Is config_sync_directory defined, and is it outside the web root?
• Is the exported configuration committed, and does the repository contain the same file count as a fresh export?
• Does your deployment run database updates before configuration import?
• Is every environment-specific value in $config overrides rather than in an exported file?
• Is settings.local.php excluded from version control?
• Does anyone actually read the configuration diff in a pull request, or is it rubber-stamped?

That last one is the difference between configuration management working and merely existing. The diff is the review; a permission change is one line of YAML and it is easy to wave through.

The part core does not do

Configuration management handles deployment. It does not handle updates. Core has no unattended update mechanism: the staging API package_manager is marked lifecycle: experimental and hidden: true in its own info file, and the user-facing Automatic Updates module is contributed. Core's Update Status module reports that a release exists and stops there.

So security patching is a scheduled human task, or a managed host's job, or a retainer. It is the single most common gap on otherwise well-run Drupal sites, and it is worth writing into the runbook next to the deployment steps.

Common questions

Why did my configuration change disappear after deployment?

You changed it on the server. The import replaced the active configuration with what is in the files. Make the change locally, export, commit, deploy.

Should I commit the configuration directory?

Yes. That is the entire point — it is what makes the site's structure reviewable and reproducible.

What if the import reports missing content?

You have exported configuration that references content — a block placement pointing at a content block that does not exist on the target, typically. Create the content first, or reconsider whether that placement should be in configuration.

Do I need Composer for all of this?

For managing code, yes. Configuration export and import can be done through the administration interface, though the command line is faster and scriptable. The learning roadmap covers where Composer fits in the wider picture.

How do I handle a multisite installation?

Each site gets its own configuration directory and its own settings.php. Shared code, separate configuration. Plan the directory layout before the second site exists, not after.

Where to take this

If you are setting this up for the first time, get the sync directory and the deployment order right before anything else; everything after is refinement. If you are inheriting a site where none of this exists, the audit is a day's work and it is the highest-value day you will spend on it.

For a build where deployment has to be dependable rather than improvised, Drupal development services covers the workflow, and describing your current setup is enough for me to tell you which of the six checks above you are failing.