Create a New Project

In step two of the Build Tools guide, learn how to create a new Build Tools project.

Discuss in our Forum Discuss in Slack

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. You may need to delete and re-install the Terminus Build Tools plugin to get the most recent version.

  1. Install Composer.

    • Verify your installation with composer --version:

      composer --version
      Composer version 1.10.6 2020-05-06 10:28:10
  2. Install the most recent release of Terminus.

    • Verify your installation with terminus --version:

      terminus --version
      Terminus 2.3.0
  3. Add an SSH key in your User Dashboard to enable passwordless access and avoid authentication prompts. Otherwise, provide your Pantheon Dashboard credentials when prompted.

  4. Generate a Pantheon machine token, then authenticate Terminus.

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

    mkdir -p ~/.terminus/plugins
  6. Install the Terminus Build Tools Plugin:

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

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. Optionally, you may 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.

Create a Build Tools Project

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 9:

    terminus build:project:create --git=github --team='My Agency Name' d9 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


View Your New Project Repo

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:

Initial Project Page shows title of project in GitHub