Converting your Drupal project to the Git reference deployment method

Introduction

This guide provides instructions on converting your Drupal project structure from the Drupal-specific Git reference deployment method to a format compatible with the Git reference deployment method.

Prerequisites

Before you begin, ensure you have:

• Access to your project’s environment-specific files.
• Basic understanding of file and script management within your Drupal project.
• Familiarity with Git and deployment practices.

Step 1: Move environment-specific files

Begin by moving your environment-specific files from the etc/drupal directory to the .dropsolid/scaffold directory. Perform these steps for each environment in your project.

• Move etc/drupal/settings_[environment]_override.php or etc/drupal/settings_[environment].php to .dropsolid/scaffold/[environment]/docroot/sites/default/settings.php.
• Move etc/drupal/robots_[environment].txt or etc/drupal/robots.txt to .dropsolid/scaffold/[environment]/docroot/robots.txt.
• Move etc/drupal/htaccess_[environment].txt or etc/drupal/.htaccess to .dropsolid/scaffold/[environment]/docroot/.htaccess.

Optionally, merge the contents of additional_settings.[environment].php into the corresponding settings_[environment].php file. This is not mandatory, as settings_[environment].php will still include additional_settings.[environment].php from its original location.

Step 2: Move update scripts

Next, move the update scripts from the bash/updates directory to the .dropsolid/scaffold directory. Do this for each environment in your project.

• Move bash/updates/update_[environment].sh to .dropsolid/scaffold/[environment]/deploy.sh. Update any paths in the script to reflect its new location in the project root.
• Move any additional scripts you want to run during deployment to the same location within .dropsolid/scaffold/[environment].

Step 3: Create platform.deploy.yml

In each environment's scaffolding directory, create a platform.deploy.yml file at .dropsolid/scaffold/[environment]/platform.deploy.yml and include the following content:

sync:
  exclude:
    - docroot/sites/default/files
    - tmp
    - private/files
tasks:
  after_sync:
    - type: shell
      script: "deploy.sh"

Add any additional exclusions or scripts as needed. If platform.deploy.yml is identical for all environments, you can place a single file in your application root (above the docroot directory).

Step 4: Create __templates for new environments

To facilitate the creation of new environments with the new deployment flow, create a __templates directory inside .dropsolid/scaffold. This directory will be copied to .dropsolid/scaffold/[environment] during environment creation and should include:

• .dropsolid/scaffold/__templates/docroot/sites/default/settings.php
• .dropsolid/scaffold/__templates/platform.deploy.yml
• .dropsolid/scaffold/__templates/deploy.sh

Replace placeholders in these files with tokens.

Example of token replacement in settings.php

For example, replace the following in etc/drupal/settings_[environment].php:

<?php
      $db_name = '[[ database_name ]]';
      $db_user = '[[ database_user ]]';
      $db_pass = '[[ database_password ]]';
      $db_host = '[[ database_host ]]';
      $db_port = '[[ database_port ]]';
      $db_driver = 'mysql';
      $db_prefix = '';

[...]
      $settings['hash_salt'] = '[[ env_secret_key ]]';

[...]

      // List of trusted IPs (IP numbers of our reverse proxies)
      $settings['reverse_proxy_addresses'] = array_merge(['127.0.0.1'], explode(',','[[ proxy_ips ]]'));

      // Now that token support is in you can also use a token to determine Drupal's deployment identifier
      $settings['deployment_identifier'] = \Drupal::VERSION . '[[ unix_timestamp_at_deploy_time ]]';

      if (file_exists(DRUPAL_ROOT . '/../etc/drupal/additional_settings.[[ environment_name ]].php')) {
        include DRUPAL_ROOT . '/../etc/drupal/additional_settings.[[ environment_name ]].php';
      }
[...]

Do the same for the settings.php files you've moved to .dropsolid/scaffold/[environment]/docroot/sites/default/settings.php.

The hash_salt value may change

The [[ env_secret_key ]] token will differ from the current hash salt, which may invalidate existing one-time logins. The hash salt is used for one-time login links, cancel links, form tokens, and related functionalities.

Example of token replacement in deploy.sh

In bash/updates/update_[environment].sh, replace the following:

#!/bin/sh
[...]
  # Ensure CMI knows about the split.
  ${DRUSH} config_import_single:single-import ../config/sync/config_split.config_split.[[ environment_name ]].yml
[...]

Token replacement only works for files inside .dropsolid/scaffold. This replacement occurs before the files are copied to their final locations.

Step 5: Change the deployment method

After completing the above steps, update your environment’s deployment method by following the instructions on the Switching the deployment method page.