What Is Build Tools?
Build Tools is a project that encompasses multiple Pantheon-maintained repositories that work together to connect the tools and automation necessary for an advanced WebOps workflow.
The main goals of the Build Tools project are to:
- Ease the creation of new projects on Pantheon, making use of an external Git provider and a Continuous Integration (CI) service.
- Add additional commands to Terminus to make tasks common in an automated workflow easier.
Pantheon Build Tools Repositories
The repositories that are a part of Build Tools are:
- Terminus Build Tools Plugin - Extends Pantheon's Terminus command-line interface with a collection of commands useful for projects with an external Git provider and a CI.
- Template Repositories - Repositories for WordPress and Drupal 8 that include an opinionated set of workflows and deployment scripts. These are templates or examples; not frameworks. They are meant to be a one-time starting point for new projects and customized as needed.
- By default, when creating a new Build Tools project one of these example repositories is used as a starting point. Custom starters are also supported.
- Build Tools CI Dockerfile - A Dockerfile, which is deployed to quay.io, for use in CI environments. It contains common tools such as Terminus and the Terminus Build Tools plugin.
These tools work together to help you create and manage your own projects that follow the Build Tools workflow.
A Build Tools Project's Components
There are three main components to a project created with Build Tools:
- A supported Git and CI combination:
This is an overview of how Build Tools works while using Github and Circle CI:
Master Composer, automated testing, and other advanced workflow concepts with help from our experts. Pantheon delivers custom workshops to help teams master our platform and improve their WebOps workflow.
Build Tools Workflow
Build Tools projects extend the Pantheon workflow by adding an external Git provider and a CI service.
In this workflow, only files unique to the project are tracked as part of the external Git repository. The CI then builds a production artifact, deploys the fully built site to Pantheon, and runs a suite of automated tests.
This is quite different than working with the Pantheon-hosted Git repository for each site, where all code must be committed.
Is Build Tools The Right Tool?
It's easy to create a Build Tools project, but you should also understand what all of the components are doing and how they work together. This is not a "set it and forget it workflow," but rather an entry point for projects requiring automated workflows.
Build Tools projects have many benefits. However, there is also added complexity and maintenance. You and your team, must decide when the benefits outweigh the additional complexity and maintenance.
In general, Build Tools is a good fit for a project if the project needs are complex enough to require a more complex workflow, and you and your team are comfortable with command-line tools and bash scripts and wish to use a CI to automate the build, deploy, and test the project workflow.
Pantheon's support team cannot troubleshoot issues with third-party services like GitHub or CircleCI.
Build Tools Changelog
- [closed] Github api warning on create new project #323
- [closed] /bin/bash: ./.ci/build/php: Permission denied - both on Bitbucket and Github/CircleCI #314
- [bug] Document required authentication details #257
- [enhancement] Make the update-db + cache-clear functions a responsibility of build:env:create #222
- [documentation] Document lack of Windows support #162
- [closed] Bitbucket Support #145
- [closed] BT-27: Use GIT_SSH_COMMAND for pushing to Pantheon [#188](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/188)
- [closed] BT-29: Support for custom build asset messages. [#190](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/190)
- [closed] BT-39: Only build on pull requests [#191](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/191)
- [closed] BT-24: Provide opportunity to correct mis-entered credentials [#194](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/194)
- [closed] Running tests for 324 [#338](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/338)
- [closed] Test run for #328 [#337](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/337)
- [closed] Adds missing message to pantheon push [#328](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/328)
- [closed] Added support for changing the admin username [#325](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/325)
- [closed] Regex needs to be multiline. [#321](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/321)
- [closed] Respect gitignore file when building in Integrated Composer mode. [#319](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/319)
- [closed] Adjust pattern so that all ssh key fixtures are cleaned up [#309](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/309)
- [closed] Add scheduled CLU task creation to Bitbucket provider startTesting task [#304](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/304)
- [enhancement] Remove unused use declarations [#303](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/303)
- [closed] Add configuration example for self-hosted GitLab hostname. [#286](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/286)
- [enhancement] Allow source_branch and sha for GitLab branch name in branchesForPullRequests output [#299](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/299)
- [closed] Retrieve GitLab merge request states individually. [#301](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/301)
- [closed] Add documentation for build:project:create options [#293](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/293)
- [closed] Support private Composer repos with
TERMINUS_BUILD_TOOLS_COMPOSER_AUTHenv variable [#292](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/292)
- [closed] Remove Bitbucket limitation in README [#291](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/291)
- [closed] Introduce
--use-sshto perform initial repo push over SSH [#279](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/279)
- [closed] Better docs for build:comment:add:commit and build:comment:add:pr [#285](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/285)
- [closed] Update 'build:env:create' to comment on a PR instead of a commit [#280](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/280)
- [closed] Add some documentation around
- [closed] referencing beta16, as that's the latest release. [#273](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/273)
- [closed] Allow underscores in GitLab tokens [#272](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/272)
- [closed] Allow git providers to provide build secrets. [#268](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/268)
- [closed] Update
BitbucketAPIto handle API data pagination [#267](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/267)
- [closed] Make
getPagerInfo()more flexible and typehint [#264](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/264)
- [closed] Fix PHP notices when interacting with BitBucket API data [#263](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/263)
- [closed] Mark
branchesForPullRequestsmethod public [#260](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/260)
- [bug] Bitbucket privacy [#256](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/256)
- [closed] Uncaught Error: Class 'Pantheon\TerminusBuildTools\ServiceProviders\RepositoryProviders\Bitbucket\PullRequestInfo' not found [#212](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/212)
- [closed] Revert to build:env:push if build:env:create is run against dev [#248](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/248)
- [closed] Test D8 and GitLab [#245](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/245)
- [closed] Documentation updates [#243](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/243)
- [closed] Allow git providers to override build metadata. [#200](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/200)
- [closed] Build assets on project creation if command exists [#207](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/207)
- [closed] Introduce unit testing and test URL parsing. [#240](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/240)
- [closed] Clear Composer cache before running build:project:create [#242](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/242)
- [closed] Readme Clarifications [#201](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/201)
- [closed] Gracefully fail if build:env:create source and multidev are the same [#227](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/227)
- [closed][#199](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/199) - add tokenKey method for bitbucket trait [#229](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/229)
- [closed] Add functionality and a flag to allow github private repositories. [#226](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/226)
- [closed] Allow setting the region when creating a site [#225](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/225)
- [closed] Add support for creating scheduled GitLab Pipeline [#232](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/232)
- [closed] allow build:env:create to clone test, live, etc [#224](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/224)
- [closed] BT-36: Fix another problem with merge to master [#189](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/189)
- [closed] BT-30: Support for a build-providers.json file [#193](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/193)
- [closed] Remove note about GitLab limitation and Drupal sites. [#195](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/195)
- [closed] BT-13: Bitbucket pipelines. [#180](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/180)
- [closed] BUGS-2589: Test build:env:merge [#186](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/186)
- [closed] Add temporary environment variable detection to GitLab URL detection [#187](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/187)
- [closed] BUGS-2589: Fix crash with build:env:delete:pr / :ci [#185](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/185)
- [closed] BT-5: build:project:repair [#182](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/182)
- [closed] BT-19: Fix terminus build:env:delete:pr for GitLab [#175](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/175)
- [closed] Update Circle API calls to prevent 500 error [#183](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/183)
- [closed] Split out GitHub API as a separate object called by the GitHub service provider [#181](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/181)
- [closed] BT-12: Update documentation including GitLab instructions [#177](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/177)
- [closed] BT-32: Update cloneFiles / cloneDatabase API calls [#176](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/176)
- [closed] Make sure that we process all of the pages in a paged API request [#173](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/173)
- [closed] Updated readme with a link to the installation [#124](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/124)
- [closed] BT-6: Gitlab Provider Support [#169](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/169)
- [closed] BT-20: Ensure that automatic multidev deletion is working correctly [#171](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/171)
- [closed] Backport of #147 to 1.x branch [#149](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/149)
- [closed] BT-28: Update to Terminus 2 [#170](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/170)
- [closed] Fixes logic issues in branch-preservation [#128](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/128)
- [closed] fix: correct regular expression to parse project [#164](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/164)
- [closed] Clarify help text for build:env:delete:pr [#133](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/133)
- [closed] backport of #158 to 1.x branch [#160](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/160)
- [closed] Set ssh key gen to use PEM format to address Issue #158 . with CircleCI [#159](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/159)
- [closed] Nick wilde1990 improved bitbucket support [#136](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/136)
- [closed] Philltran improved bitbucket support [#152](https://github.com/pantheon-systems/terminus-build-tools-plugin/issues/152)
2.0.0 Beta 17
- Allow git providers to provide build secrets. (#268)
- Allow underscores in GitLab tokens (#272)
- Add documentation around
--use-sshto perform initial repo push over SSH (#279)
- Update 'build:env:create' to comment on a PR instead of a commit (#280)
- Better docs for
- Add configuration example for self-hosted GitLab hostname. (#286)
- Remove Bitbucket limitation in README (#291)
- Support private Composer repos with
TERMINUS_BUILD_TOOLS_COMPOSER_AUTHenv variable (#292)
- Add documentation for build:project:create options (#293)
- Allow source_branch and sha for GitLab branch name in branchesForPullRequests output (#299)
- Retrieve GitLab merge request states individually (#301)
- Remove unused use declarations (#303)
- Add scheduled CLU task creation to Bitbucket provider
2.0.0 Beta 16
BitbucketAPIto handle API data pagination (#267)
getPagerInfo()more flexible and typehint (#264)
- Fix PHP notices when interacting with BitBucket API data (#263)
- BitBucket's API response is shaped differently than GitHub and GitLab. The values themselves are nested in a
branchesForPullRequestsmethod public (#260)
- Properly parse the BitBucket visibility flag (#256)
- Add missing use statement in BitbucketProvider (#212)
2.0.0 Beta 15
- Revert to
build:env:createis run against dev (#248)
2.0.0 Beta 14
- Private repository support for
- Allow setting the Pantheon region during
- Build assets on project creation if command exists (#207)
- Add support for creating scheduled GitLab Pipeline (#232)
- Add Drupal 8 GitLab test (#245)
- Allow git providers to override build metadata (#200)
- Gracefully fail if build:env:create source and multidev are the same (#227)
- Documentation updates (#243)
- Clear Composer cache before running
build:project:createin tests (#242)
We just released Build Tools 2.0. If you need help troubleshooting issues or getting set up, please reach out via the Build Tools issue queue and the maintainers would be happy to help you.
As Terminus does not support Windows, Build Tools does not either. You can install Terminus Build Tools on macOS or Linux. Windows 10 users can install the Windows Subsystem for Linux.