Understanding the Drupal 8/9 Configuration Management workflow

In this article, we are going to cover the Drupal 8 configuration lifecycle. We will start by making a simple configuration change in our local environment, then export the change to code, and eventually deploy it to different environments on Acquia Cloud.

Prerequisites

This guide assumes Acquia’s ‘vcs’ directory exists, your site’s configuration was successfully exported and changes were committed and pushed to your Git repository. Please refer to Acquia vcs config directory vs. Drupal 8/9 sync directory and Configuration management for Drupal 8 for more information about Configuration Management on Acquia Cloud.

Additionally, knowledge of Drush config commands is strongly recommended as the guide makes heavy use of them. Also, we are assuming that multiple site aliases that correspond to each Acquia Cloud environment are setup properly (e.g. @sitename.dev, @sitename.prod, etc).

Make changes locally

In Drupal 8, Views are configuration entities, which makes them a great candidate for Configuration Management workflow. Let’s start by adding a new field "Authored on" to the default "Content" view:

1. Go to /admin/structure/views/view/content
2. Add the "Authored on" views field and configure it as needed.
3. Save the view.

Export changes to configuration directory

The modified "Content" view only resides in the "config" database table, which is also known as the "active" configuration store. In order to deploy those changes to other environments or share them with other developers, we need to export them to YAML files into Acquia Cloud's vcs configuration directory. We will use Drush because it provides for very convenient export and import commands.

Export via Drush:

$ drush @sitename.local config-export vcs
 
Differences of the active config to the export directory:
 
 Collection  Config              Operation
             views.view.content  update
The .yml files in your export directory (/../docroot/../config/default) will be deleted and replaced with the active config. (y/n)

Note that we export the configuration to the vcs directory (in our example, config/default) deliberately rather that Drupal's default sync directory. This is because Acquia Cloud expects the former so that you can track configuration changes under version control. See Acquia vcs config directory vs. Drupal 8/9 sync directory for more details.

In this instance, only views.view.content is being modified in the active datastore. Once you confirm replacing the existing configuration file, the view in the export directory will match the view in the active store (database). Before you push new code to the remote dev environment, make sure they reflect your desired changes:

$ git diff 
 
diff --git a/config/default/views.view.content.yml b/config/default/views.view.content.yml
index c1976dd..6491f5b 100644
--- a/config/default/views.view.content.yml
+++ b/config/default/views.view.content.yml
@@ -355,6 +355,73 @@ display:
           hide_alter_empty: true
           destination: true
           plugin_id: entity_operations
+        created:
+          id: created
+          table: node_field_data
+          field: created
+          relationship: none
+          group_type: group
+          admin_label: ''
+          label: 'Authored on'

Deploy changes to the remote Dev environment

Now that changes have been exported to the config directory, we need to add them to the code repository in order to synchronize them effectively to Acquia Cloud environments.

Hint: the following git command could be issued after establishing an SSH connection to your dev environment. Alternatively, you could issue git commands from your local environment if Drush aliases are set up properly.

Note: for the sake of simplicity, we’ll assume commits are pushed to the develop branch and it’s checked out in our Dev environment. Your workflow may vary, though. For example, it might be recommended to push code to a separate feature branch like task/123-content-view.

$  git checkout develop
$  git add --all . && git commit -m "Add Authored on field to Content view"
$  git push origin develop

Your Acquia Cloud dev environment should now have an updated config directory. However, /admin/content doesn't include the "Authored on" field we've just added in code. The reason why is changes need to be imported from the config directory to the active configuration store. Importing changes can be accomplished either manually or by configuring your CI solution (e.g. Jenkins or Acquia Cloud CD) to trigger a config import upon pushing new commits to the code repository.

We recommend Drush to manually import changes from the vcs config directory. Doing this will replace the "Content" views configuration in the database with the one we recently introduced in code:

$ drush @sitename.dev config-import vcs
 
 Collection  Config              Operation
             views.view.content  update
Import the listed configuration changes? (y/n):

Refresh admin/content and rebuild Drupal caches if necessary. Please see Cloud API and Cloud CD for methods to automate configuration integration.

Deploy changes to remaining environments

It’s time to merge our changes for testing on the stage environment.

Note: we assume that changes are merged into the master branch for purpose of testing. Also, the Acquia Cloud stage environment is using code from the same branch.

On your local machine merge the develop branch into the master branch using the following Git commands:

$ git checkout master
$ git merge develop
$ git push origin master

Next, import changes to your staging environment

$ drush @sitename.test config-import vcs
 
 Collection  Config              Operation
             views.view.content  update
Import the listed configuration changes? (y/n):

Refresh admin/content and rebuild Drupal caches if necessary. By now, the staging environment should reflect changes we introduced locally.

After QA, you can then deploy changes to the prod environment by using the same technique.