Git reference deployment method¶

Introduction¶

This guide covers the general Git reference deployment method, its requirements, and how files and folders are synced during deployment. This method is primarily used by non-Drupal projects and select Drupal projects.

For information on how to start a deployment, see the Deploying to an environment page.

Unlike the Drupal-specific Git reference deployment method, this approach leverages a platform.deploy.yml file, allowing the project itself to define which folders are synced and what post-deployment tasks are executed. This provides flexibility and eliminates hardcoded exceptions.

Overview of the deployment method¶

The Git reference deployment method uses a Git reference (such as a staging branch) to check out your project and deploys all files and folders except those specified in the platform.deploy.yml file. After syncing, any tasks defined in the after_sync section of the platform.deploy.yml are executed.

To use this method successfully, the Git reference must adhere to specific requirements related to file structure and project contents.

Requirements for successful deployment¶

The following prerequisites must be met to ensure a smooth deployment:

All necessary files for running the application must be committed to Git.
Your project must follow the application structure guidelines.

The deploy file (`platform.deploy.yml`)¶

The platform.deploy.yml file is key to customizing your deployment. It specifies which files to sync and defines pre- and post-deployment tasks.

Filename: platform.deploy.yml
Location: Should be placed in the project root after scaffolding. If identical across environments, it can be committed directly to the root.

Example structure:

sync:
  exclude:
    - docroot/media
    - tmp
    - docroot/app/config/local.php
    - docroot/index_dev.php

tasks:
  before_sync:
    - type: shell
      script: "pre-deploy.sh"
  after_sync:
    - type: shell
      script: "pre-deploy.sh"
      run_on_all_webservers: true
    - type: shell
      script: "deploy.sh"

Scaffolding¶

This method supports scaffolding within the .dropsolid/scaffold folder at the root of the project.

Environment-specific folders: Located within .dropsolid/scaffold, each environment has its own folder ( e.g., dev), which contains files to be scaffolded during deployment.
Templates: The __templates folder is used when new environments are created. Its contents are copied to a new environment's folder to provide the necessary scaffolding files.

Warning

Only files that are scaffolded have token replacement support.

Example: Scaffolding the `dev` environment¶

For a project like florista, deploying to the dev environment involves the following files inside .dropsolid/scaffold/dev:

docroot/robots.txt
docroot/.htaccess
docroot/sites/default/settings.php (this file contains tokens with database credentials)
platform.deploy.yml
pre-deploy.sh
deploy.sh

During deployment, all tokens are replaced and the files are copied to the application folder, overwriting existing files if necessary. The result is a fully scaffolded environment.

Pre-deployment script¶

After scaffolding is completed, the system looks for a platform.deploy.yml file and runs any scripts listed under the tasks.before_sync section. These pre-deployment scripts are synced to the server and executed by the environment user. They are useful for tasks like performing backups or checking application integrity. If any pre-deployment script returns a non-zero exit code, the deployment process will stop.

Additionally, there is an optional key, run_on_all_webservers, which is set to false by default. This option is beneficial for applications running on a multi-server setup, such as our High Availability (HA) offering. When set to true, the specified task will run on all webservers. This can be useful, for example, to clear the opcache on all webservers.

Syncing¶

Once the pre-deployment tasks are completed, the system reads the platform.deploy.yml file to identify files or directories that should be excluded from syncing. It then uses a single rsync operation to transfer all remaining files to the application folder on the server, ensuring that the specified exclusions are respected.

Post-deployment tasks¶

After syncing, the system executes any tasks listed under tasks.after_sync in platform.deploy.yml, again running them as the environment user. These tasks typically involve running shell scripts to complete the deployment process.

Like pre-deployment tasks, post-deployment tasks also support the run_on_all_webservers option, which is set to false by default. For multi-server setups, such as our HA offering, setting this key to true ensures the specified task runs on all webservers. This can be particularly helpful for clearing opcache across multiple servers.

Templates for new environments¶

The __templates folder within .dropsolid/scaffold is used when creating new environments. Its contents are copied into the newly created environment’s scaffold folder, ensuring that each environment has the required files and configuration from the outset.