Deploying Drupal Sites with Confidence: Leveraging Config Management and Config Split

Problem: Hard‑to‑Track Site Settings

When a Drupal developer pushes a change to a live site, there’s always a risk that a configuration tweak made in a local environment (e.g., a custom mailer, a new content type, or a theme setting) slips into production unnoticed. Traditional manual edits or ad‑hoc scripts leave the site vulnerable to drift, security leaks, and hard‑to‑reproduce bugs.

Goal: Use Drupal’s built‑in configuration system to treat every setting as code, version‑control it, and deploy it safely across all environments.

Thesis: Treat Configuration Like Code

Drupal’s core Config API stores every setting in a YAML file. When you run drush config:export the system writes a snapshot of the entire configuration tree to sites/default/files/config_HASH. Importing that snapshot on another site restores the exact same state. Coupled with the Config Split module (or the core split feature in Drupal 10), you can keep environment‑specific values out of the main export and avoid accidental leaks.

Section 1 – Exporting and Importing Configuration

Exporting is the first step in turning configuration into code.

# Run on the source site (dev, staging, etc.)
# Requires Drush and site admin rights
$ drush config:export
# Output:
#   Exported 123 config entities into /sites/default/files/config_HASH

After export, commit the config_HASH directory to your Git repository. The directory contains .yml files for every configuration entity (e.g., system.site.yml, node.type.article.yml, block.block.footer.yml).

Importing on another environment is just the reverse:

# On staging or production
$ drush config:import
# Output:
#   Imported 123 config entities.

Verification: Run drush config:status after import. If everything is up‑to‑date, it will report "No configuration differences." Any discrepancy indicates a drift that needs to be investigated.

Section 2 – Keeping Environment‑Specific Settings Separate with Config Split

Some settings should never leave a dev environment—for example, a local mail server, test URLs, or debug modules. Config Split lets you define splits that override the base configuration when a specific environment is detected.

Example split definition (in config/sync/config_split.settings.yml):

development:
  status: true
  label: "Development override"
  include:
    - system.site
    - mail.system
  exclude:
    - block.block.frontpage
  config_path: "config/split/development"

Place the overriding YAML files (e.g., config/split/development/system.site.yml) in the split directory. When drush config:export runs on a dev site, it will include the split files; on production, they’re ignored.

Risk: Over‑splitting can clutter the config tree. Keep splits minimal—only for truly environment‑specific values.

Section 3 – A Concrete Example: Deploying a New Block

Assume you added a custom block footer_info in dev. The steps are:

1. Export on dev: drush config:export – the block’s YAML appears in block.block.footer_info.yml.
2. Commit to Git: Add the file to the repo and push.
3. Pull on staging: Pull the latest changes.
4. Import on staging: drush config:import. Verify the block appears on the site.
5. Repeat on prod: Pull and import to the production server. Ensure drush config:status shows no differences.

Checks: After each import, run drush block:list to confirm the block’s status and placement. If you see "Missing config" errors, the import failed.

Section 4 – Trade‑offs and Limitations

• Security risk: Exporting from a live site can surface sensitive data (e.g., SMTP passwords). Exclude such entities or use config:export --partial with a filter.
• Complexity: Heavy use of Config Split can make the config tree difficult to navigate. Document each split and its purpose.
• Custom modules: If a module’s configuration schema is missing or incorrect, config:import will fail. Test custom module imports in a staging environment first.
• Version drift: If you manually edit YAML files, you risk breaking the schema. Prefer using the UI or drush commands to make changes.

Actionable Closing

1. Enable the Config Split module (or use Drupal 10’s core split feature). 2. Define minimal splits for truly environment‑specific settings. 3. Use drush config:export and config:import in CI/CD pipelines, with Git hooks to enforce review. 4. Verify after each import with drush config:status or automated tests that compare expected config hashes. 5. Avoid exporting live production data unless you’ve masked sensitive fields.

With these steps, Drupal configuration becomes a first‑class citizen of your codebase, reducing drift, preventing accidental data leaks, and making deployments predictable and repeatable.