Deploy Drupal Site Configuration Using Drush and Git

Desired outcome

Export Drupal site configuration to YAML, store it in Git, and import it on another environment so that content types, fields, views, roles and site settings are identical across dev, staging and production.

Prerequisites

• Drupal core 9.5 or later (or Drupal 10) with Drush 12+ installed.
• Access to the command line on each environment with permissions to run drush and write to the config/sync directory.
• A Git repository initialized and accessible from each environment.
• The site UUID must be known or set to the same value on all environments.

Procedure

1. Prepare the development environment
   1. Log in to the dev site admin UI and make the configuration change (e.g., add a field to an article content type).
   2. Run drush config:export (alias cex) to write all active configuration to config/sync.
   3. Verify the export: ls config/sync/*.yml should show updated files.
2. Commit configuration to Git
   1. From the repository root, add the changed YAML files: git add config/sync.
   2. Commit with a descriptive message: git commit -m "Add field subtitle to article content type".
   3. Push to the remote: git push origin main.
3. Deploy code and configuration to target environment
   1. On the target (staging or production) server, pull the latest code and config: git pull origin main.
   2. Clear Drupal caches to ensure the system reads the latest YAML: drush cr.
   3. Run database updates if any code changes require them: drush updatedb -y.
   4. Import the configuration: drush config:import (alias cim).
4. Verify the import
   1. Check for differences: drush config:status should report "No differences".
   2. Spot‑check a known change in the admin UI (e.g., the new field appears on the article edit form).
   3. Review the recent watchdog log for import errors: drush watchdog:show --type="php" --limit=10 or admin/reports/dblog.

Recovery options

If the import fails or produces an unwanted state:

• Roll back the Git commit that introduced the bad YAML: git revert <commit‑hash>.
• Pull the reverted state on the target environment and run drush config:import again.
• As a safety net, keep a database dump taken before the import; restoring the dump returns the site to its pre‑import configuration.

Limitations and practical checks

• Configuration import does not delete content; removing a content type that still has nodes will fail or leave orphaned data. Verify that no content depends on the removed element before importing.
• Environment‑specific values (API keys, SMTP credentials) should be kept out of config/sync using the Config Split or Config Ignore contributed modules, or overridden in settings.php via $config['system.site']['name'] = 'Staging Site';.
• Drush command names and flags can differ between Drush 9 and Drush 12; consult drush --version and the relevant documentation for your installed version.