Synchronizing Drupal Configuration Across Environments Using Config Management

Desired outcome

Keep site configuration identical across development, staging, and production environments while allowing environment‑specific overrides (e.g., debug mode, API keys) without manual copy‑pasting.

Prerequisites

• Drupal 8, 9, or 10 installed on each target environment.
• Drush 10+ available and configured to point to the Drupal root of each environment.
• Git (or another VCS) repository initialized with the project code.
• File system permissions that allow the web‑server user (commonly www-data or apache) to read and write the configuration sync directory.
• The config_split module installed and enabled if you need environment‑specific splits.

Step‑by‑step procedure

1. Choose a sync directory

   In settings.php (or settings.local.php) set:

   $settings['config_sync_directory'] = '../config/sync';

   Place the directory outside the web root but within the project repository so it can be version‑controlled.

2. Export configuration from the source environment (e.g., development)

   Run:

   drush config:export -y --destination=../config/sync

   This writes YAML files representing the active configuration to the sync directory.

3. Commit the exported config

   Add, commit, and push the changes:

   git add config/sync
    git commit -m "Export configuration from dev (YYYY‑MM‑DD)"
    git push origin main

4. Pull the config on the target environment (e.g., staging)

   On the staging server:

   git pull origin main
    drush config:import -y --source=../config/sync

   Drush will compare the active config with the YAML files and apply any differences.

5. Handle environment‑specific splits (optional)

   If you use config_split to exclude debug settings or API keys:

   • Create a split (e.g., dev) via the UI at admin/config/development/config_split.
   • Export the split configuration:

     drush config:export -y --destination=../config/split/dev

   • Add the split directory to .gitignore so the actual split files are not committed, but keep the split definition (the config_split.config_split.* YAML) in sync.
   • On each environment, enable the appropriate split:

     drush config-set config_split.split.dev status 0 -y   # disable on production
      drush config-set config_split.split.dev status 1 -y   # enable on dev/staging

Expected checks

1. List pending changes before importing:

   drush config:status

   The output should show no "pending" items if the export and import are in sync.

2. Clear caches after import to ensure new config is active:

   drush cr

3. Verify a specific setting (e.g., site name) via Drush:

   drush cget system.site name

   Compare the output with the value in the YAML file.

4. Check logs and status report for configuration errors:
   • Watchdog: drush watchdog:show --type="php" --limit=10
   • Status report: visit admin/reports/status or run drush status and look for the "Configuration system" section.

Recovery / rollback options

Because config:import changes the active configuration, you can revert to a known good state:

1. Reset the Git branch to the commit before the unwanted export:

   git reset --hard 
    git push --force origin main  # use with caution

2. Re‑export the configuration from the reset state and import it on the target environment:

   drush config:export -y --destination=../config/sync
    drush config:import -y --source=../config/sync
    drush cr

3. If only a few items are wrong, you can re‑import a single configuration object:

   drush config:import --partial --source=../config/sync system.site

Limitations and practical tips

• Configuration UUIDs must match across environments; moving config between sites with different UUIDs will cause import failures. Always export/import from the same site clone or use drush config:edit to correct UUIDs only when you understand the impact.
• The config_split module does not automatically keep split files out of the sync directory; you must manually add the split folder to .gitignore.
• Large numbers of configuration items can make drush config:status slow; consider filtering with drush config:status --list-only or checking specific modules.
• Never edit configuration directly in the database on a live site; changes made there will be lost on the next import.
• After any import, always clear caches (drush cr) and verify the site behaves as expected before declaring the operation successful.