Terminus Build Tools Plugin

Build Tools is a Terminus Plugin that contains a collection of commands useful for projects making use of an external Git provider and Continuous Integration (CI) along with Pantheon.

Table of Contents

1. Project Purpose
2. Requirements
3. Installation
4. Setup
5. Available Services
6. Commands
7. Customization
8. Build Tools Command Examples
9. Help
10. Related Repositories

Project Purpose

The main purposes of the Build Tools project are to:
Ease the creation of new projects making use of an external Git provider, a Continuous Integration service, and Pantheon.
This is primarily done through the build:project:create commands, which scaffolds new projects from a template repository and performs one-time setup, such as configuring SSH keys and environment variables, needed to connect an external Git provider and CI service with Pantheon. For detailed set-up instructions, see the Terminus Build Tools Guide. To use your own template repository see Customization.
Add additional commands to Terminus to make tasks common in an automated CI workflow easier.
See Commands and Build Tools Command Examples for details.

Requirements

• If you are using Terminus 3, you must use the Build Tools 3.x release.
• If you are using Terminus 2, you must use the Build Tools 2.x release.

PHP 7.2 or greater is recommended.

Installation

Installing Build Tools 3.x:

terminus self:plugin:install terminus-build-tools-plugin

Installing Build Tools 2.x:

mkdir -p ~/.terminus/plugins
composer create-project --no-dev -d ~/.terminus/plugins pantheon-systems/terminus-build-tools-plugin:^2

Note about dev dependencies

The Terminus Build Tools plugin should be installed without dev dependencies. If you install the plugin with a different method, such as cloning this source repository, use composer install --no-dev to download the project dependencies.

Setup

It is recommended that you use one of the provided example projects as a template when creating a new project. All of the example projects use Terminus 3 and Build Tools 3.x.
The default template repositories are each assigned an abbreviation, as shown below:

• WordPress: wp
• Drupal 9: d9
• Drupal 8: d8
• Drupal 7: d7

More details about these template repositories see Template Repositories in this document or visit the links above.
You can get started with one of these examples by using the build:project:create command:

$ terminus build:project:create --team='My Agency Name' wp my-site

This command will create:

• A Pantheon site
• A GitHub repository
• A CircleCI test configuration

It will prompt you for the credentials it needs to create these assets. While GitHub and CircleCI are the defaults, other providers are supported as well. See available services for details.
Note: After running this command, if you get an error “There are no commands defined in the “build:project” namespace”, then you may need to install this Terminus plugin first as described in Requirements, above.
Note: It is important to specify the name of your agency organization via the --team option. If you do not do this, then your new site will be associated with your user and will not have the capability to create multidev environments.

Available Services

The build:project:create command supports services in the following combination:

Git Host
CI Service

GitHub
CircleCI

GitHub
Github Actions

GitLab
GitLabCI

BitBucket
CircleCI

Note: if using Github Actions, token should have the “workflow” scope.

Starting a new GitLab Project

$ terminus build:project:create --git=gitlab --team='My Agency Name' wp my-site

Starting a new BitBucket Project

$ terminus build:project:create --git=bitbucket --team='My Agency Name' wp my-site

Starting a new Github/Github Actions Project

$ terminus build:project:create --ci=githubactions --team='My Agency Name' wp my-site

Limitations

Bitbucket

• Composer Lock Updater isn’t working quite yet.

Commands

The following commands are available as part of the Build Tools plugin.

build:project:create

The build:project:create command is used to initialize projects within the Git PR workflow. Automated setup of the Pantheon website along with the corresponding Git and CI provider is included.

Command Options

Additional options are available to further customize the build:project:create command:

Option
Description

–pantheon-site
The name to use for the Pantheon site (defaults to the name of the Git site)

–team
The Pantheon team to associate the site with

–org
The Git organization to place the repository in (defaults to authenticated user)

–label
The friendly name to use for the Pantheon site (defaults to the name of the Git site)

–email
The git user email address to use when committing build results

–test-site-name
The name to use when installing the test site

–admin-password
The password to use for the admin when installing the test site

–admin-email
The email address to use for the admin

–admin-username
The username to use for the admin

–stability
The stability to use with composer when creating the project (defaults to dev)

–keep
The ability to keep a project repository cloned after your project is created

–use-ssh
The ability to perform the initial git push to the repository provider over SSH instead of HTTPS

–ci
The CI provider to use. Defaults to “circleci”

–git
The git repository provider to use. Defaults to “github”

–visibility
The visibility of the project. Defaults to “public”. Use “public” or “private” for GitHub and “public”, “private”, or “internal” for GitLab

–region
The region to create the site in. See the Pantheon regions documentation for details.

–template-repository
Private composer repository to download template or git url if using the expanded version when no composer repository.

–ci-template
Git repo that contains the CI scripts that will be copied if there is no ci in the source project.

If you want to use a private composer repository, you should provide the credentials like this:

export TERMINUS_BUILD_TOOLS_COMPOSER_AUTH=json_encoded_string

or in ~/.terminus/config.yml file under build-tools.composer-auth.
Then, in the build:project:create command, pass a composer-repository option like this:

terminus build:project:create --template-repository="https://repo.packagist.com/myorg" myorg/myrepo my-project

If you want to use git repository that has not been published to packagist as your template, you should do it like this:

terminus build:project:create --template-repository="git@github.com:myorg/myrepo.git" myorg/myrepo-template my-project

The package name in the composer.json file into the template repo should be “myorg/myrepo-template”. If myorg/myrepo is a private repo, you should have access to it in your current terminal.
You can also use the following shorthand:

terminus build:project:create git@github.com:myorg/myrepo.git my-project

and build tools will figure out the right package name for you.
You can find more info about composer repositories, private packages, cli authentication and authentication methods in the official composer documentation.
See terminus help build:project:create for more information.

build:project:repair

The build:project:repair command is used to repair projects that were created with the Build Tools plugin. This is useful for rotating credentials, such as provider authentication tokens.

Command Options

Additional options are available to further customize the build:project:repair command:

Option
Description

–env
The environment variables you would like to set on the CI system

build:comment:add:commit

The build:comment:add:commit command is used to add a comment to a commit on the Git Provider. This is useful in CI scripts for commenting as multidev environments are created or other code feedback is determined.
Either the --message and/or the --site_url options are required.

Command Options

Additional options are available to customize the build:comment:add:commit…