Skip to main content
Last Reviewed: December 13, 2021

Create a New Project

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

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. Refer to A Build Tools Project's Components for the supported combinations.


Ensure you have the latest versions of Terminus and the Terminus Build Tools plugin installed. You may want to run terminus self:plugin:update pantheon-systems/terminus-build-tools-plugin to ensure you have the most recent version.

  1. Install Composer.

    • Verify your installation with composer --version:

      composer --version
      Composer version 2.1.8 2021-09-15 13:55:14
  2. Install the most recent release of Terminus.

    • Verify your installation with terminus --version:

      terminus --version
      Terminus 3.0.1
  3. Add an SSH key in your Personal Workspace.

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

  5. Install the Terminus Build Tools Plugin:

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

Access Tokens (Optional)

The Build Tools plugin will prompt you to create access tokens for the services you use as an alternative to a password. Access tokens are stored as environment variables. Access token requirements vary by service. Read below for specific access token requirements.

  • GitHub: The GitHub token checks for the following scopes:

    • repo (required)

    • delete-repo (optional)

    • workflow (required if using Github Actions)

  • CircleCI: No scopes are configurable for this token.

  • Gitlab: The Gitlab token requires the following scopes:

    • api

    • read_repository

    • write_repository

  • Bitbucket: A Bitbucket app password requires the following scopes:

    • Projects (read)

    • Repositories (read and write)

    • Pull Requests (read and write)

    • Pipelines (edit variables)

Optionally, you can generate your tokens ahead of time and manually export them to the local variables. Note that Bitbucket requires a user name and password instead of a token. Review the local variable export examples below:


The examples below vary depending on what services you use. Replace exampleToken (or exampleUserName and exampleUserPassword if you use Bitbucket) with your token or Bitbucket user name and password.

export GITHUB_TOKEN=exampleToken
export CIRCLE_TOKEN=exampleToken
export GITLAB_TOKEN=exampleToken
export BITBUCKET_USER=exampleUserName
export BITBUCKET_PASS=exampleUserPassword

Navigate to your project settings page in CircleCI if you need to replace a token.

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, refer to 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:

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

Host a Static Site on Pantheon

Use Build Tools to help host a static site or files on Pantheon.

Composer Content-Length Mismatch and/or Degraded Mode

If you encounter an issue such as:

The "" file could not be downloaded: failed to open stream: Operation timed out
Retrying with degraded mode, check for more info
The "" file could not be downloaded: failed to open stream: Operation timed out could not be fully loaded, package information was loaded from the local cache and may be out of date

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.

Your requirements could not be resolved to an installable set of packages

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 site name is already taken on Pantheon

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>

Additional Support

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:

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