Information for: DEVELOPERS   PARTNERS

Continuous integration

Acquia BLT provides automation commands used in most macOS and Linux environments. The Acquia BLT automation commands intend to be used both locally and on continuous integration (CI) platforms.

Acquia BLT natively supports the following CI solutions:

Acquia BLT provides one default instruction file (such as .travis.yml or acquia-pipelines.yml) for each of the CI solutions, allowing you to quickly have a working build. To use the default instruction file, you must run the following initialization command. The command will copy the default instruction file to the required location, in the same manner that Drupal requires you to copy default.settings.php to settings.php.

The instruction files are intended for customization. Acquia will provide updates to the default instruction files, but merging those updates into your customized files is your responsibility.

Workflow

The typical CI workflow is as follows:

  1. A pull request or commit to GitHub triggers a CI build.
  2. The CI tool reads and executes an instruction file. The instruction file executes Acquia BLT commands to build and test your application. For example, the CI tool completes the following tasks:
    • Builds Composer dependencies.
    • Lints and validates code.
    • Installs Drupal.
    • Runs tests such as PHPUnit and Behat against the installed instance of Drupal.
  3. The CI tool reports the status of the build (success or failure) back to GitHub.
  4. If the build is successful, you merge the pull request.
  5. The merge triggers another CI build, builds, and tests your application again, and generates an artifact suitable for deployment.
  6. The CI tool deploys the artifact. If you automate deployment, the deployment is Continuous Deployment.

Acquia Cloud pipelines feature

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

To initialize pipelines feature support for your Acquia BLT project, complete the following steps:

  1. Connect the pipelines service to your GitHub or Bitbucket repository

  2. Initialize pipelines for your project by running the following command:

    blt recipes:ci:pipelines:init
    

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

  3. Commit the new file, and push then it to your Acquia Git remote by using commands based on the following example:

    git add acquia-pipelines.yml
    git commit -m 'Initializing pipelines integration.'
    git push origin
    
  4. 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 feature will generate a new branch on your Acquia Cloud subscription named pipelines-[source-branch]-build. The branch will contain a deployment artifact deployable to an Acquia environment.

Additional information

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

If you encounter problems, see Troubleshooting pipelines feature issues.

Travis CI

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

Configuring Travis CI for automated deployments

You must configure Acquia Cloud, GitHub, and Travis CI to work together to configure the workflow. To do this, complete the following steps:

Note

The following instructions apply only to private GitHub 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 to allow Travis to authenticate to Acquia Cloud:

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

    Do not use a passphrase. Instead, name the SSH key something different than your normal Acquia Cloud key (such as travis).

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

  3. Create a new Acquia Cloud account used primarily as a container for the SSH keys granting Travis push access to Acquia Cloud. You can create a new account by inviting a new team member on Teams in Acquia Cloud using an email address such as <email>+<project>.travis@acquia.com. The team member must have SSH push access with the Team Lead role. Acquia does not 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 Acquia Cloud 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 do not have administrative control over your repository, you cannot 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 Acquia Cloud 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 Acquia Cloud Git repository’s server host name to ssh_known_hosts in your .travis.yml file. Ensure you remove the user name and file name (example.git) and use only the host name:

    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 Acquia Cloud 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.

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

Configuring Travis CI for automated deployments on several branches

You can watch several branches on GitHub for deployment (for example, master, and integration) by adding another provider block to the deploy section of your project’s .travis file as indicated in the following code. You can add several provider blocks, as needed.

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