Pantheon Named Major Player IDC Marketscape: 2021 Vendor Assessment Learn More

Managing Configuration in Code: Drupal 8

This is the second post in a series on managing site configuration in code. You can find part one here, which introduces the idea of managing site configuration in code.

Drupal 8 Configuration System Introduction

The Drupal 8 configuration system is designed to systematize the process of moving configuration between different environments of the same site—e.g. development, staging and production. It is not intended to migrate configuration from one site to another since configuration data as the site and import files must have matching UUID values in the configuration. If you wish to migrate configuration from one site to another then check out the Drupal 8 Features Module.

Configuration Deployment Workflow

Assuming you have three environments—development, test, and live—the production database is treated as the canonical source for data—both content and configuration. The development environment will have a mix of code changes, e.g. PHP files, and configuration changes, exported to code with the Drupal 8 configuration system.

Both code and configuration changes, which have been exported code, are deployed to the test environment. The database from the live environment is also copied to the test environment to ensure the latest content exists in the test environment. At this point the configuration changes are imported from code into the database. You may also want to copy the latest media uploads from live to the test environment as well.

The test environment now has the latest code and configuration from the development environment, and the latest content and media from the live environment. It is a mirror of what the live environment would look like if you were to deploy the latest code and configuration changes.

After performing quality assurance and testing on the test environment and receiving stakeholder approval, you can deploy the code and configuration files to live with confidence. After deploying to live, simply import the configuration changes from code to the live database with the Drupal configuration system.

A Practical Example: Add a Sidebar

You have been tasked with adding a new sidebar to a Drupal 8 site. This consists of adding a region to your theme, creating a custom block to use in the sidebar, and adding the block to the region. Creating the region and custom block are standard code changes but deploying the new region without any configuration would leave the sidebar empty.

After adding the code for the region and custom block to the development environment you use the Drupal 8 administrative interface to place the custom block, and any other desired blocks, in the new region. Once the blocks are configured in the region export the configuration to code with the Drupal 8 configuration system.

Now you have the code and configuration, exported as code, together. These can both be committed to version control and deployed together. Once deployed, the configuration can be imported into the database of the new environment.

The import can be done with Drush using the config import command. Since Drush is a command line tool, this can be scripted and automated with each deployment. If you would like to do this on Pantheon checkout our Quicksilver example for drush config import.


As you can see, deploying your configuration with your code saves time as you no longer have to repeat the configuration in the Drupal administration interface on each environment. It can also be automated—removing room for error—and tracked in version control. I encourage you to start using the configuration system when working with any Drupal 8 project.

Additional Resources

Drupal Documentation:

Third Party Articles:

The Latest Stack + The Latest Drupal: Learn more about Drupal 8 on Pantheon. 

Topics Development, Drupal