Skip to main content

Pantheon Build Tools integration

Build Tools

Pantheon came up with a boilerplate setup that uses Github, CircleCI, and Multidev to have a really nice development workflow. The main idea is that for each pull request there will be a dedicated multidev environment that we run all kinds of testing including visual regression.

More information on this is


There is an easy way to run visual regression testing with Diffy in this setup. After multidev environment is completed we trigger a job to take screenshots from it and compare them with the Dev environment. Dev environment usually follows the `master` branch.



Once you follow instructions from you already have a setup ready for your pull requests. Also, we expect you to have a Diffy account.

Now you need to create a Diffy project that will be used for testing your builds.

Make sure you set up a DEV environment for your configuration as it will be used to test your builds against.

Project settings DEV environment is needed
Project settings DEV environment is required


Use Terminus command to configure integration

There is a Terminus command available to help you set up the integration.


In order to install the Terminus command run

composer create-project --no-dev -d $HOME/.terminus/plugins diffywebsite/diffy-terminus-build-tools-plugin:^2.0.0-beta1


Then you can run the command


It will ask for your API key (see how to get it) and you will be able to select your existing project in Diffy.

It is best to run this command after you have set up your drops project. In this way, all credentials to CirlceCI and information about the site are still in cache. Our custom command depends on them being available.


Manually set up CircleCI variables for Diffy

If something didn't work that well for automated configuration with Terminus command -- you can always provide environment variables manually.

For that, you need to go to your CircleCI project settings and manually add two variables DIFFY_API_KEY and DIFFY_PROJECT_ID.

CircleCI project settings


CircleCI add Variable


Integration in Action

Once you have completed the setup of the configuration you can go ahead and create a pull request. Remember that in order to trigger visual regression testing you need to add an [vr] in your commit message. So your commit message can look like

Bigger banner on homepage [vr]

Here is how a message in a pull request will look like in case of some changes were found.

Diffy pull request message


Configure the CircleCI setup

Diffy has a CircleCI orb that can be used for settings up a job. You can find instructions to set it up at

Use Diffy Orb