Last Reviewed: 2025-12-10

Create a New Project

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

Discuss in Slack

Edit this page on GitHub Report an issue with this doc

In this section, we will use the Terminus Build Tools Plugin to create a new project consisting of a Git repository, Composer, a Continuous Integration (CI) service, and a Pantheon site with Automated Testing. This guide will get you started, but you will need to customize and maintain the CI/testing set up for your projects.

Requirements

• Composer
• Terminus
• Terminus Build Tools Plugin
• PHP version 7.2 or greater
• An SSH key in your Personal Workspace.
• A Pantheon machine token, to authenticate Terminus.

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:

• GITHUB_TOKEN
• CIRCLE_TOKEN
• GITLAB_TOKEN
• BITBUCKET_USER and BITBUCKET_PASS

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.

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:

• Start a GitHub project with Drupal:

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

Review Important Directories and Update File Paths

/web Directory

Your site is stored and served from the /web subdirectory located next to the pantheon.yml file. You must store your website in this subdirectory for a Composer-based workflow. Placing your website in the subdirectory also allows you to store tests, scripts, and other files related to your project in your repo without affecting your web document root. It also provides additional security by preventing web access to files outside of the document root through Pantheon. Your files may still be accessible from your version control project if it is public. See the pantheon.yml documentation for details.

1. Verify that your website is stored in the /web subdirectory.

composer.json File

This project uses Composer to manage third-party PHP dependencies. Some files, such as core CMS packages inside the /web directory, may not be visible in the repository. This is because the CMS (Drupal or WordPress) and its plugins/modules are installed via Composer and ignored in the .gitignore file.

Third-party dependencies, such as modules, plugins and themes, are added to the project via composer.json file. The composer.lock file keeps track of the exact dependency version. For WordPress, Composer installer-paths are used to ensure the dependencies are downloaded into the appropriate directory.

1. Place all dependencies in the require section of your composer.json file.

   • This includes dependencies that are only used in non-Live environments. All dependencies in the require section are pushed to Pantheon.

2. Place all dependencies that are not a part of the web application but are necessary to build or test the project in the require-dev section.

   • Example dependencies are php_codesniffer and phpunit. Dev dependencies are deployed to Dev and Multidev environments, but not to Test and Live environments.

Continuous Integration

The scripts that run on Continuous Integration are stored in the .ci directory. Provider-specific configuration files, such as .circle/config.yml and .gitlab-ci.yml use these scripts.

The scripts are organized into subdirectories according to their function:

• Build
• Deploy
• Test

Build Scripts .ci/build

• .ci/build script builds an artifact suitable for deployment.

• .ci/build/php installs PHP dependencies with Composer.

Build Scripts .ci/deploy

All scripts stored in the .ci/deploy directory facilitate code deployment to Pantheon.

• .ci/deploy/pantheon/create-multidev creates a new Pantheon Multidev environment for branches other than the default Git branch. Note that not all users have Multidev access. Please consult the Multidev FAQ doc for details.

• .ci/deploy/pantheon/dev-multidev deploys the built artifact to either the Pantheon Dev or a Multidev environment, depending on the Git branch.

Automated Test Scripts .ci/tests

The .ci/tests scripts run automated tests. You can add or remove scripts depending on your testing needs.

Static Testing

• .ci/test/static and tests/unit are static tests that analyze code without executing it. These tests are good at detecting syntax errors but not functionality errors.

• .ci/test/static/run runs PHP CodeSniffer with WordPress coding standards (for WordPress sites), PHP Unit, and PHP syntax checking.

• tests/unit/bootstrap.php bootstraps the Composer autoloader.

• tests/unit/TestAssert.php provides an example Unit test.

1. Create all project-specific test files in the tests/unit directory.

Visual Regression Testing

The scripts stored in the .ci/test/visual-regression directory run visual regression testing through a headless browser to take screenshots of web pages and compare them for visual differences.

• .ci/test/visual-regression/run runs BackstopJS visual regression testing.

• .ci/test/visual-regression/backstopConfig.js is the BackstopJS configuration file.

1. Update the settings in .ci/test/visual-regression/backstopConfig.js file for your project.

   • For example, the pathsToTest variable determines the URLs to test.

GitHub Actions

This section provides information enabling GitHub Actions for your site.

The Build Tools Site will configure GitHub Actions automatically if it was passed as the selected CI when creating the site. You will need to consult advanced external resources if you're working with an existing non-Build Tools site and want to add Github Actions.

The steps to enable GitHub Actions for an existing Build Tools site created with another CI (for example, CircleCI) shown below might work for you.

1. Copy .ci/.github to .github.

2. Add the following secrets to the Github Actions configuration:

   • ADMIN_EMAIL

   • ADMIN_PASSWORD

   • ADMIN_USERNAME

   • TERMINUS_TOKEN

   • TERMINUS_SITE

   • SSH_PRIVATE_KEY

   • GH_TOKEN

Working Locally with Lando

Complete the one-time steps below to get started using Lando for local development. Please note than Lando is an independent product and is not supported by Pantheon. Refer to the Lando documentation for more information.

1. Install Lando if it is not already installed.

2. Clone your project repository from GitHub to your local.

3. Manually create a .lando.yml file with your preferred configuration, based on the WordPress recipe.

4. Run lando start to start Lando.

5. Save the local site URL.

   • The local site URL should look similar to: https://<PROJECT_NAME>.lndo.site.

6. Run the command below to download dependencies.

7. Run the command below to download the media files and database from Pantheon.

8. Visit the local site URL saved in the preceding steps.

   • You should now be able to edit your site locally. The steps above do not need to be completed on subsequent starts. You can stop Lando with lando stop and start it again with lando start.

9. Run all Composer, Terminus and wp-cli commands in Lando instead of the host machine.

   • This is done by prefixing the desired command with lando. For example, after a change to composer.json run lando composer update rather than composer update.

Troubleshooting

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: