We are working on a new 2.x version of the Terminus Build Tools plugin with Terminus 2 support. In the meantime, you can test the beta release following the instructions below. If you have an issue with the plugin, review the issue queue. If you need to update to the latest version, see updating plugin docs.
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 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 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 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.
Master Composer concepts with help from our experts. Pantheon delivers custom workshops to help development teams master the platform and improve internal WebOps.
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:
One advantage of managing code this way is that it keeps the change sets (differences) for pull requests as small as possible. If a pull request upgrades several dependencies, only the dependency metadata file will change; the actual code changes in the upgraded dependencies themselves are not shown.
GitHub pull requests (PRs) are a formalized way of reviewing and merging a proposed set of changes to the source repository. When one member of a development team makes changes to a project, all of the files modified to produce the feature are committed to a separate branch, and that branch becomes the basis for the pull request. GitHub allows other team members to review all of the differences between the new files and their original versions, before merging the PR to accept changes.
Before You Begin
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
Add an SSH key within your User Dashboard to enable passwordless access and avoid authentication prompts. Otherwise, provide your Pantheon Dashboard credentials when prompted.
Generate a Machine Token, then authenticate Terminus:
terminus auth:login --machine-token=<machine-token>
$HOME/.terminus/pluginsdirectory if it does not already exist:
mkdir -p $HOME/.terminus/plugins
Install the Terminus Composer Plugin:
composer create-project -n --no-dev -d $HOME/.terminus/plugins pantheon-systems/terminus-composer-plugin:~1
Install the Terminus Drupal Console Plugin:
composer create-project -n --no-dev -d $HOME/.terminus/plugins pantheon-systems/terminus-drupal-console-plugin:~1
Install the Terminus Build Tools Plugin. Update the version number in this example from 2.0.0-beta18 to the current version:
composer create-project --no-dev -d $HOME/.terminus/plugins pantheon-systems/terminus-build-tools-plugin:^2.0.0-beta18
The Terminus Build Tools Plugin does not support private repositories.
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.
Pantheon's support team cannot troubleshoot issues with third-party services like GitHub or CircleCI.
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
export GITHUB_TOKEN=yourGitHubToken export CIRCLE_TOKEN=yourCircleCIToken
If you need to replace a token, navigate to your project settings page in CircleCI.
Build Tools Changelog
2.0.0 Beta 17
- Allow git providers to provide build secrets. (#268)
- Allow underscores in GitLab tokens (#272)
- Add documentation around
--use-sshto perform initial repo push over SSH (#279)
- Update 'build:env:create' to comment on a PR instead of a commit (#280)
- Better docs for
- Add configuration example for self-hosted GitLab hostname. (#286)
- Remove Bitbucket limitation in README (#291)
- Support private Composer repos with
TERMINUS_BUILD_TOOLS_COMPOSER_AUTHenv variable (#292)
- Add documentation for build:project:create options (#293)
- Allow source_branch and sha for GitLab branch name in branchesForPullRequests output (#299)
- Retrieve GitLab merge request states individually (#301)
- Remove unused use declarations (#303)
- Add scheduled CLU task creation to Bitbucket provider
2.0.0 Beta 16
BitbucketAPIto handle API data pagination (#267)
getPagerInfo()more flexible and typehint (#264)
- Fix PHP notices when interacting with BitBucket API data (#263)
- BitBucket's API response is shaped differently than GitHub and GitLab. The values themselves are nested in a
branchesForPullRequestsmethod public (#260)
- Properly parse the BitBucket visibility flag (#256)
- Add missing use statement in BitbucketProvider (#212)
2.0.0 Beta 15
- Revert to
build:env:createis run against dev (#248)
2.0.0 Beta 14
- Private repository support for
- Allow setting the Pantheon region during
- Build assets on project creation if command exists (#207)
- Add support for creating scheduled GitLab Pipeline (#232)
- Add Drupal 8 GitLab test (#245)
- Allow git providers to override build metadata (#200)
- Gracefully fail if build:env:create source and multidev are the same (#227)
- Documentation updates (#243)
- Clear Composer cache before running
build:project:createin tests (#242)