In this section, we will use the Terminus Build Tools Plugin to create a new project consisting of a Git repository, a Continuous Integration service, and a Pantheon site.
These instructions are written with GitHub as the Git provider repository, CircleCI as the CI, and a Pantheon site.
Substitute your chosen Git Provider and CI service in these instructions with the options of your choice. See A Build Tools Project's Components for the supported combinations.
Make sure you have the latest versions of Terminus and the Terminus Build Tools plugin installed.
Verify your installation with
composer --version Composer version 1.10.6 2020-05-06 10:28:10
Install the most recent release of Terminus.
Verify your installation with
terminus --version Terminus 2.3.0
Add an SSH key in your User Dashboard to enable passwordless access and avoid authentication prompts. Otherwise, provide your Pantheon Dashboard credentials when prompted.
Generate a Pantheon machine token, then authenticate Terminus.
$HOME/.terminus/plugindirectory if it does not already exist:
mkdir -p ~/.terminus/plugins
Install the Terminus Build Tools Plugin:
composer create-project --no-dev -d ~/.terminus/plugins pantheon-systems/terminus-build-tools-plugin:^2.0.0
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. Optionally, you may 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.
Scaffold a new project from a template repository and perform a one-time setup to connect an external Git provider and CI service with Pantheon. This setup also configures SSH keys and environment variables. To use your own template repository see Customization in the Build Tools Plugin documentation.
Modify the commands in the following examples to match your project's needs.
Start a GitHub project with WordPress:
terminus build:project:create --git=github --team='My Agency Name' wp my-site
Start a GitHub project with Drupal 8:
terminus build:project:create --git=github --team='My Agency Name' d8 my-site
The script will ask for additional information such as tokens/credentials for GitHub and the associated CI.
For a list of all available command options, see the Build Tools Project README
As packages pulled by Composer are updated (along with their dependencies), version compatibility issues can pop up. Sometimes you may need to manually alter the version constraints on a given package within the
require-dev section of
composer.json in order to update packages. See the updating dependencies section of Composer's documentation for more information.
As a first troubleshooting step, try running
composer update to bring
composer.lock up to date with the latest available packages (as constrained by the version requirements in
If you encounter an issue such as:
The "https://packagist.org/packages.json" file could not be downloaded: failed to open stream: Operation timed out Retrying with degraded mode, check https://getcomposer.org/doc/articles/troubleshooting.md#degraded-mode for more info The "https://packagist.org/packages.json" file could not be downloaded: failed to open stream: Operation timed out https://packagist.org could not be fully loaded, package information was loaded from the local cache and may be out of date [Composer\Downloader\TransportException] Content-Length mismatch create-project [-s|--stability STABILITY] [--prefer-source] [--prefer-dist] [--repository REPOSITORY] [--repository-url REPOSITORY-URL] [--dev] [--no-dev] [--no-custom-installers] [--no-scripts] [--no-progress] [--no-secure-http] [--keep-vcs] [--no-install] [--ignore-platform-reqs] [--] [<package>] [<directory>] [<version>] [error] Command `composer create-project --working-dir=/private/var/folders/lp/7_1gh83s5mn9lwfjvqqlf1lm0000gn/T/local-sitevPumRP pantheon-systems/example-wordpress-composer pantheon-wp-composer-project -n --stability dev` failed with exit code 1
This indicates a network-level issue. We recommend contacting your Internet Service Provider (ISP) for support. One way to reduce connection woes is to use a non-standard channel with less activity/noise on wireless modems.
Check the output for the recommended fix. For example, PHP
7.0 is required for WordPress. Once you have resolved the issues as suggested by Composer try the command again.
The following error occurs when running
terminus build:project-create before authenticating your session with Terminus:
BuildToolsCommand.php line 166: The site name exampleuniquesitename is already taken on Pantheon.
To resolve, generate a Machine Token, then authenticate Terminus and try the build command again:
terminus auth:login --machine-token=<machine-token>
Pantheon's Composer-based example repositories are maintained and supported on GitHub. After browsing existing issues, report errors in the appropriate repository's issue queue:
Once your site is ready, the URL to your project page will be printed in the terminal. Copy this address and paste it into a browser to visit your new project on Github: