Skip to content

Manage multidev environments for a Pantheon site using a GitHub PR workflow.

Notifications You must be signed in to change notification settings

populist/terminus-build-tools-plugin

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

63 Commits
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Terminus Build Tools Plugin

CircleCI Terminus v1.x Compatible

Terminus Plugin that contains a collection of commands useful during the build step on a Pantheon site that manages its files using Composer, and uses a GitHub PR workflow with Behat tests run via Circle CI (or some other testing service).

An example circle.yml file has been provided to show how this tool should be used with CircleCI. When a test runs against a "canonical" repository on GitHub, the following things will happen:

  • Git is configured for making clones and commits.
  • Terminus 1.x is installed.
  • The oldest multidev testing environments are deleted.
  • A build step is fired off via composer build-assets.
  • A new multidev environment is created for testing.
  • The build artifacts are pushed up to the test environment.

When a PR is merged to the master branch, then the test PR is merged into the dev environment if the test passes.

Testing multidev environments are divided into two groups: environments used for testing pull requests, and environments used for testing other kinds of builds (e.g. tagged releases, commits or merges to master, and so on). PR test environments persist until the PR branch on GitHub is deleted. The other test environments are deleted just before a new testing environment is created. The most recent three of these environments remain, and the rest are deleted.

See below for the list of supported commands. This plugin is only available for Terminus 1.x.

Configuration

In order to use this plugin, you will need to set up a GitHub repository and a CircleCI project for the site you wish to build. Credentials also need to be set up.

Credentials

In order to use the build-env:create-project command, the first thing that you need to do is set up credentials to access GitHub and Circle CI. Instructions on creating these credentials can be found on the pages listed below:

These credentials may be exported as environment variables. For example:

#!/bin/bash
export GITHUB_TOKEN=[REDACTED]
export CIRCLE_TOKEN=[REDACTED]

If you do not export these environment variables, you will be prompted to enter them when you run the build-env:create-project command.

Create a New Project Quickstart

EXPERIMENTAL: The build-env:create-project is under development. Backwards compatibility not guarenteed until version 1.3.0.

To create a new project consisting of a GitHub project, a Pantheon site, and Circle CI tests, first set up credentials as shown in the previous section, and then run the build-env:create-project command as shown below:

terminus build-env:create-project --team="Agency Org Name" d8 example-site

This single command will:

  • Create a new GitHub repository named example-site, cloned from the started site repository.
  • Create a new Pantheon site built from the GitHub repository.
  • Configure CircleCI to run Behat tests on the site on every pull request.
  • Configure credentials on all of these services to allow the test scripts to run.

Note that 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 not have the capability to create multidev environments. In this instance, all of your tests will run on the dev environment. See Running Tests without Multidevs, below, for more information.

In the example above, the parameter d8 is shorthand for the project pantheon-systems/example-drops-8-composer, the canonical Composer-managed Drupal 8 site for Pantheon. You may replace this parameter with the GitHub organization and project name for any other canonical starter site that you would like to use.

Starter Site Shorthand Packagist Project Name
Drupal 8 d8 pantheon-systems/example-drops-8-composer
Drupal 7 d7 pantheon-systems/example-drops-7-composer

More starter sites will be available in the future. You may easily create your own by following the example of the existing starter site, and publishing your customized version on Packagist. At the moment, there is no way to extend the list of shorthand site names, though.

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

Option Description
--pantheon-site The name to use for the Pantheon site (defaults to the name of the GitHub site)
--team The Pantheon team to associate the site with
--org The GitHub org to place the repository in (defaults to authenticated user)
--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

See terminus help build-env:create-project for more information.

Build Customizations

To customize this for a specific project:

  • Define necessary environment variables in the Circle project settings file circle.yml:
    • TERMINUS_SITE: The name of the Pantheon site that will be used in testing.
    • TERMINUS_TOKEN: A Terminus OAuth token that has write access to the terminus site specified by TERMINUS_SITE.
    • GIT_EMAIL: Used to configure the git user’s email address for commits we make.
    • GITHUB_TOKEN: Optional, if needed.
  • Customize dependencies: as needed to install additional tools.
  • Replace example test: section with commands to run your tests.
  • Add a build-assets script to your composer.json file.
  • Add any needed cleanup steps (e.g. drush updatedb) after build-env:merge.

PR Environments vs Other Test Environments

Note that using a single environment for each PR means that it is not possible to run multiple tests against the same PR at the same time. Currently, no effort is made to cancel running tests when a new one is kicked off; if the concurrent build is not cancelled before a new commit is pushed to the PR branch, then the two tests could potentially conflict with each other. If support for parallel tests on the same PR is desired, then it is possible to eliminate PR environments, and make all tests run in their own independent CI environment. To do this, make the following change in the environments section of the circle.yml file:

    TERMINUS_ENV: $CI_LABEL

Running Tests without Multidevs

To use this tool on a Pantheon site that does not have multidev environments support, it is possible to run all tests against the dev environment. If this is done, then clearly it is not possible to run multiple tests at the same time. To use the dev environment, make the following change in the environments section of the circle.yml file:

    TERMINUS_ENV: dev

** IMPORTANT NOTE: ** If you initially set up your site using terminus build-env:create-project, and you do not use the --team option, or the team you specify is not an Agency organization, then your Circle configuration will automatically be set up to use only the dev environment. If you later add multidev capabilities to your site, you will need to visit the Circle CI environment variables configuration page and delete the entry for TERMINUS_ENV.

Examples

The examples below show how some of the other build-env commands are used within test scripts. It is not usually necessary to run any of these commands directly.

Create Testing Multidev

terminus build-env:create my-pantheon-site.dev ci-1234

This command will commit the generated artifacts to a new branch and then create the requested multidev environment for use in testing.

Push Code to an Existing Multidev

terminus build-env:push-code my-pantheon-site.dev

This command will commit the generated artifacts to an existing multidev environment, or to the dev environment.

Merge Testing Multidev into Dev Environment

terminus build-env:merge my-pantheon-site.ci-1234

Delete Testing Multidevs

terminus build-env:delete my-pantheon-site '^ci-' --keep=2 --delete-branch

List Testing Multidevs

terminus build-env:list

Installation

For help installing, see Manage Plugins

mkdir -p ~/.terminus/plugins
composer create-project -d ~/.terminus/plugins pantheon-systems/terminus-build-tools-plugin:~1

Help

Run terminus list build-env for a complete list of available commands. Use terminus help <command> to get help on one command.

About

Manage multidev environments for a Pantheon site using a GitHub PR workflow.

Resources

Stars

Watchers

Forks

Packages

No packages published

Languages

  • PHP 100.0%