Introduction

Create a site that manages its files using Composer, and uses a GitHub PR workflow with Behat tests run via Circle CI.

Contributors: Greg Anderson, Steve Persch, Andrew Taylor, Rachel Whitton.

Tweet

 Warning

The current version of the Build Tools plugin is designed for Terminus 1.x, and is not yet compatible with current versions of Terminus. We are working on a new version of the Terminus Build Tools plugin with Terminus 2 support and will update this guide once it is released. In the meantime, you can test the beta release.

This guide describes how to use build tools such as GitHub and CircleCI with Composer to implement a collaborative, team-based Continuous Integration workflow using Pull Requests for Drupal 8 sites on Pantheon. While this guide demonstrates Drupal 8, the same workflow can be applied to WordPress and Drupal 7 sites.

GitHub

GitHub Logo

GitHub is an online service that provides cloud storage Git repositories that may be cloned and used locally, or edited directly through their web-based management interface. These features are very useful to teams collaborating on a project together.

CircleCI

CircleCI Logo

CircleCI provides hosted services to run automated tests for a project, and GitHub provides an integration to run these tests to whenever a change is submitted. The process of testing each set of changed files prior to merging them into the main branch is called continuous integration.

Composer

Composer Logo

Composer is a PHP dependency manager that provides an alternative, more modern way to manage the external code used by a project. For example, Composer may be used to install the plugins, modules and themes used by a Drupal or WordPress site.

Automation Training

Master Composer concepts with help from our experts. Pantheon delivers custom workshops to help development teams master the platform and improve internal WebOps.

Artifact Deployment

Only files unique to the project are tracked as part of the project's main "source" repository on GitHub, which requires an abstraction layer to compile dependencies and deploy an entire "artifact" to the site repository on Pantheon. The abstraction layer is facilitated by CircleCI in the Pantheon maintained examples, but the principles are the same for other continuous integration service providers.

Composer is used to fetch dependencies declared by the project as part of a CircleCI build step. This ensures that the final composed build results are installed on Pantheon:

Artifact Deployment

Before You Begin

  1. Install Composer.

  2. Install the most recent release of Terminus:

    curl -O https://raw.githubusercontent.com/pantheon-systems/terminus-installer/master/builds/installer.phar && php installer.phar install

  3. Add an SSH key within your User Dashboard to enable passwordless access and avoid authentication prompts. Otherwise, provide your Pantheon Dashboard credentials when prompted.

  4. Generate a Machine Token, then authenticate Terminus:

    terminus auth:login --machine-token=<machine-token>

  5. Create the $HOME/.terminus/plugins directory if it does not already exist:

    mkdir -p $HOME/.terminus/plugins

  6. Install the Terminus Composer Plugin:

    composer create-project -n --no-dev -d $HOME/.terminus/plugins pantheon-systems/terminus-composer-plugin:~1

  7. Install the Terminus Drupal Console Plugin:

    composer create-project -n --no-dev -d $HOME/.terminus/plugins pantheon-systems/terminus-drupal-console-plugin:~1

  8. Install the Terminus Build Tools Plugin. Update the version number in this example from 2.0.0-beta12 to the current version:

    composer create-project --no-dev -d $HOME/.terminus/plugins pantheon-systems/terminus-build-tools-plugin:^2.0.0-beta12

     Note

    The Terminus Build Tools Plugin does not support private repositories.

  9. Authorize CircleCI on GitHub.

    If you are redirected to the CircleCI homepage, you have already authorized the service for your GitHub account. Nice! Way to be ahead of the game.

 Note

Pantheon's support team cannot troubleshoot issues with third-party services like GitHub or CircleCI.

If you need help configuring external systems, consider joining the Community Forum or posting in our Pantheon Community Slack Channel.

Access Tokens (Optional)

The Build Tools plugin will prompt you to create access tokens for both GitHub and CircleCI, which are stored as environment variables. The GitHub token needs the repo (required) and delete-repo (optional) scopes. You may optionally generate these tokens ahead of time and manually export them to the local variables GITHUB_TOKEN and CIRCLE_TOKEN, respectively:

export GITHUB_TOKEN=yourGitHubToken
export CIRCLE_TOKEN=yourCircleCIToken

If you need to replace a token, navigate to your project settings page in CircleCI.