BLT

Continuous integration

Note

Acquia will end support for BLT on December 31, 2024. For more information on how to replace your BLT implementation with updated functionality, see You don’t need BLT on Acquia Cloud.

Continuous integration (CI) is a software engineering best practice and should be a part of any Drupal project. BLT’s automation commands perform common tasks such as site installs, tests, and artifact builds consistently across local, CI, development, and production environments. A robust CI process using BLT’s commands is critical to testing, building, and deploying your project consistently.

Workflow

The typical CI workflow is as follows:

  1. A pull request or commit to GitHub triggers a build on your CI platform.

  2. The CI platform reads and executes a series of build steps based on a script stored in your repository root directory. The build steps execute BLT commands to build and test the application incorporating changes from the pull request.

    The CI scripts provided out of the box by BLT perform the following tasks:

    • Configure the build environment to match the hosting environment.

    • Install dependencies (using Composer and, if configured, a frontend dependency manager such as NPM).

    • Lint and validate code (using tools like PHPCS). As of BLT 11, validation also includes testing for deprecated code using the Drupal Check library.

    • Install Drupal and import configuration using the chosen configuration management strategy.

    • Run automated tests (using tools like PHPUnit, and Behat) on the installed Drupal site.

  3. The CI platform reports the status of the build (success or failure) back to GitHub.

  4. If the build is successful, a code reviewer merges the pull request.

  5. The merge triggers another CI job, testing your application again and generating an artifact suitable for deployment.

  6. The CI platform pushes the artifact to a cloud hosting repository.

Out of the box, BLT handles the deployment of code artifacts to hosting repositories, but doesn’t interact with hosting providers to deploy code to specific environments. You can add such custom deployment steps to BLT’s CI scripts to create a full Continuous Deployment workflow.

Supported CI platforms

BLT natively supports the following CI platforms:

The BLT Plugins page lists a number of community-developed plugins providing support for other CI platforms.

BLT provides a template script file (such as .travis.yml or acquia-pipelines.yaml) for each of the CI platforms, allowing you to quickly have a working build that follows the default steps outlined above. You can generate this template script file for your project using the commands detailed in the following sections.

You can customize the template script files. Acquia will continuously update the default script files, but merging those updates into your customized files is your responsibility.

Cloud Platform Pipelines

Cloud Platform Pipelines is a continuous integration and continuous deployment solution built on the Cloud Platform infrastructure. For Cloud Platform users, Pipelines provides the benefit of integrating directly with a Cloud Platform subscription, which allows you to deploy build artifacts with less effort.

To initialize Cloud Platform Pipelines support for your BLT project, complete the following steps:

  1. Connect Cloud Platform Pipelines to your GitHub or Bitbucket repository

  2. Initialize Cloud Platform Pipelines for your project:

    blt recipes:ci:pipelines:init

    The preceding code will generate an acquia-pipelines.yaml file in your project root based on BLT’s default acquia-pipelines.yaml file.

  3. Change the acquia-pipelines.yaml file to specify which databases to copy into CDEs on deployment.

  4. Commit and push the new file to your Acquia Git remote using commands such as the following:

    git add acquia-pipelines.yaml
git commit -m 'Initializing pipelines integration.'
git push origin

  5. Submit a pull request to your GitHub repository.

Your new pull request will trigger a Pipelines build to begin. The pull request’s web page reflects the Pipelines build status. If merged, the Pipelines will generate a new branch on your Cloud Platform subscription named pipelines-[source-branch]-build. The branch will contain a deployment artifact deployable to an Acquia environment.

You can use the Cloud Platform Pipelines user interface or the Pipelines CLI client to review the status or logs for your build.

If you encounter problems, see FAQs and troubleshooting.

Travis CI

Travis CI is a continuous integration and continuous deployment solution. Travis can integrate with Cloud Platform, but requires more initial configuration work than the Cloud Platform Pipelines feature.

You must configure Cloud Platform, GitHub, and Travis CI to work together using the following steps:

Note

The following instructions apply to private GitHub repositories and may have security implications for public repositories.

  1. Initialize Travis CI support for your project by running the following command:

    blt recipes:ci:travis:init

  2. Run the following command to generate an SSH key locally so Travis can authenticate to Cloud Platform:

    cd ~/.ssh
ssh-keygen -t rsa -b 4096 -m PEM

    Don’t use a passphrase. Give the SSH key a unique name (such as travis).

    Due to Travis requiring legacy RSA PEM keys, you must explicitly define the format with the -m flag.

  3. Create a new Cloud Platform account used primarily as a container for the SSH keys granting Travis push access to Cloud Platform. You can create a new account by inviting a new team member on Teams in Cloud Platform using an email address such as <email>+<project>[email protected]. The team member must have SSH push access with the Team Lead role. Acquia doesn’t recommend using a personal account or re-using the shell account across projects posing a security risk, and causing deployments to fail if your account is removed from the project.

  4. Sign in to the new Cloud Platform account and add the public SSH key from the key pair generated in the preceding step by editing the profile and then clicking Credentials.

  5. Add the same public SSH key to the Deployment Keys section on your project’s GitHub settings page, located at https://github.com/acquia-pso/[project-name]/settings/keys.

    Note

    If you don’t have administrative control over your repository, you can’t have direct access to the deployment keys settings on GitHub.

  6. Add the private SSH key to your project’s Travis CI settings located at https://magnum.travis-ci.com/acquia-pso/[project-name]/settings.

  7. Add your Cloud Platform Git repository to the remotes section of your blt.yml file by running the following command and replacing [example] with your Git repository information:

    remotes:
   - [example]@svn-14671.prod.hosting.acquia.com:[example].git

  8. Add your Cloud Platform Git repository’s server host name to ssh_known_hosts in your .travis.yml file. Use only the host name and don’t include the user name and file name (example.git):

    addons:
  ssh_known_hosts:
  - svn-14671.prod.hosting.acquia.com

    Note

    If you are planning to run any drush sql-syncs or drush sql-rsync commands between Cloud Platform and your environment, be sure to add the test or stage server host to the preceding code.

Commits or merges to the develop branch on GitHub will now trigger a fully built artifact deployed to your specified remotes.

You can watch several branches on GitHub for deployment (for example, main, and develop) by adding one or more provider block to the deploy section of your project’s .travis file.

deploy:
   - provider: script
     script: "$BLT_DIR/scripts/travis/deploy_branch"
     skip_cleanup: true
     on:
       branch: integration

For information about manually deploying your project, see Deployment workflow.