Advanced Drupal 8 Configuration Management (CMI) Workflows

After implementing some larger enterprise Drupal 8 websites, I would like to share some insights, how to solve common issues in the deployment workflow with Drupal 8 CMI.

Introduction to Drupal CMI

First of all, you need to understand, how the configuration management in Drupal 8 works. CMI allows you to export all configurations and its dependencies from the database into yml text files. To make sure, you never end up in an inconsistent state, CMI always exports everything. By default, you cannot exclude certain configurations.


If you change some configuration on the live database, these configurations will be reverted in the next deployment when you use

This is helpful and will make sure, you have the same configuration on all your systems.

How can I have different configurations on local / stage / live environments?

Sometimes, you want to have different configurations on your environments. For example, we have installed a “devel” module only on our local environment but we want to have it disabled on the live environment.

This can be achieved by using the configuration split module.

What does Configuration Split?

This module slightly modifies the CMI by implementing a Config Filter. Importing and exporting works the same way as before, except some configuration is read from and written to different directories. Importing configuration still removes configuration not present in the files. Thus, the robustness and predictability of the configuration management remains. And the best thing is: You still can use the same drush commands if you have at least Drush 8.1.10 installed.

Configuration Split Example / Installation Guide

Install config_split using composer. You need need at least “8.x-1.0-beta4” and > drush 8.1.10 for this guide.

Enable config_split and navigate to “admin/config/development/configuration/config-split”

Optional: Installing the chosen module will make the selection of blacklists / greylists way more easier. You can enable chosen only on admin pages.

I recommend you to create an “environments” subfolder in your config folder. Inside this folder you will have a separate directory for every environment:

Drupal 8 Configuration Management Folders

Now you can configure your environments:

Config Split in Drupal 8 Configuration Management

The most important thing is, that you set every environment to “Inactive”. We will later activate them according to the environment via settings.php

Config Split settings with the Drupal 8 Configuration Management

Here is my example where I enable the devel module on local:

Dev Environment Example

Activate the environments via settings.php

This is the most important part of the whole setup up. Normally, we never commit the settings.php into git. But we have a [environment]-settings.php in git for every environment:

You need to add the following line to the variables-[environment].php. Please change the variable name according to your environment machine name:

If you have done everything correctly and cleared the cache you will see “active (overriden)” in the config_split overview next to the current environment.

Now you can continue using

and config_split will do the magic.

How can I exclude certain Config Files and prevent them to be overridden / deleted on my live environment?

The most prominent candidates for this workflow are webforms and contact forms. In Drupal 7, webforms are nodes and you were able to give your CMS administrator the opportunity to create their own forms.

In Drupal 8 webforms are config entities, which means that they will be deleted while deploying if the yml files are not in git.

After testing a lot of different modules / drush scripts, I finally came up with an easy to use workflow to solve this issue and give CMS administrators the possibility to create webforms without git knowledge:

Set up an “Excluded” environment

First of all, we need an “excluded” environment. I created a subfolder in my config-folder and added a .htaccess file to protect the content. You can copy the .htaccess from an existing environment, if you are lazy. Don’t forget to deploy this folder to your live system before you do the next steps.



Now you can exclude some config files to be excluded / grey-listed on your live environment:

Greylist Webform in Config Split

Set the excluded environment to “Inactive”. We will later enable it on the live / dev environment via settings.php.

Enable “excluded” environment and adapt deployment workflow

We enable the “excluded” environment on the live system via variables-live.php (see above):

In your deployment workflow / script you need to add the following line before you do a drush config-import:

The drush command “drush @live config-split-export -y excluded” will export all webforms and contact forms created by your CMS administrators into the folder “excluded”. The “drush config-import” command will therefore not delete them and your administrators can happily create their custom forms.

Benefit of disable “excluded” on local environment

We usually disable the “excluded” environment on our local environment. This allows us to create complex webforms on our local machine for our clients and deploy them as usual. In the end you can have a mix of customer created webforms and your own webforms which is quite helpful.

Final note

The CMI is a great tool and I would like to thank the maintainers of the config_split module for their great extension. This is a huge step forward making Drupal 8 a real Enterprise CMS Tool.

If you have any questions, don’t hesitate to post a comment.


Liip related services

We are already using CMI for configuration management, 90% of project completed. Now can I install config_split for remaining configuration management Else config_split we have to install in fresh/new drupal 8 installation.

Thank you.

You can easily install config_split on an existing installation. I already did that multiple times. The config-export is not changed except that the yml files will be exported to different folders. The only tricky part is, that the “excluded” folder” normally is not part of git. You have to create it on your server and then change the deplyoment script.

Wouldn’t this make Configuration Export similar to the Features module? What would then be the advantage of using configuration export over Features to handle somewhat granular migrations of a site configuration between environments?

    Definitly not. The export command is just exporting the greylisted configurations into a predefined folder. This is not comparable to features.
    Using the standard CMI Tools has a great benefit over features. You don’t have to select and care about dependencies. You always have a full and complete configuration. I tested and used features aswell some months ago and it was full of bugs. Getting a consistent configuration over multiple systems was almost impossible.

    The described workflow is tested and works flawlessly with multiple developers and multiple systems.

If you are excluding devel modules’ configuration, does it mean you have the modules enabled in all environments anyway? Because the modules are enabled based on core.extension.yml and it cannot be excluded from any environment.
Development modules should not be enabled in production.

    Woah, I should have tested this before saying anything stupid. It seems to also exclude the selected modules from from the core.extension.yml. Very niiice, like Borat would say.

Thanks for the blog post, Jon Minder. Just the information I needed. Everything in the contrib space surrounding Configuration Management seems to be developing very rapidly these days. I watched a presentation on Config Split at Drupal Mountain Camp in February and a number of things have changed since then.

Your post saved me a bunch of time. Especially the part about greylisting webforms.

Leave a Reply