pantheon-systems / terminus-build-tools-plugin
Build Tools - A Terminus plugin that contain commands to manage build assets on Pantheon.
Installs: 1 186 847
Dependents: 2
Suggesters: 0
Security: 0
Stars: 83
Watchers: 22
Forks: 68
Open Issues: 94
Type:terminus-plugin
Requires
- consolidation/version-tool: ^0.1.9
- paragonie/sodium_compat: ^1.17
Requires (Dev)
- phpspec/prophecy: ^1.16
- phpunit/phpunit: ^9
- symfony/yaml: v3.4.26
- dev-master
- 3.x-dev
- 3.0.9
- 3.0.8
- 3.0.7
- 3.0.6
- 3.0.5
- 3.0.4
- 3.0.3
- 3.0.2
- 3.0.1
- 3.0.0
- 2.x-dev
- 2.2.0
- 2.1.0
- 2.0.4
- 2.0.3
- 2.0.2
- 2.0.1
- 2.0.0
- 2.0.0-beta18
- 2.0.0-beta17
- 2.0.0-beta16
- 2.0.0-beta15
- 2.0.0-beta14
- 2.0.0-beta13
- 2.0.0-beta12
- 2.0.0-beta11
- 2.0.0-beta10
- 2.0.0-beta9
- 2.0.0-beta8
- 2.0.0-beta7
- 2.0.0-beta6
- 2.0.0-beta5
- 2.0.0-beta4
- 2.0.0-beta3
- 2.0.0-beta2
- 2.0.0-beta1
- 2.0.0-alpha6
- 2.0.0-alpha5
- 2.0.0-alpha4
- 2.0.0-alpha3
- 2.0.0-alpha2
- 2.0.0-alpha1
- 1.x-dev
- 1.3.10
- 1.3.9
- 1.3.8
- 1.3.7
- 1.3.6
- 1.3.5
- 1.3.4
- 1.3.3
- 1.3.2
- 1.3.1
- 1.3.0
- 1.2.27
- 1.2.26
- 1.2.25
- 1.2.24
- 1.2.23
- 1.2.22
- 1.2.21
- 1.2.20
- 1.2.19
- 1.2.18
- 1.2.17
- 1.2.16
- 1.2.15
- 1.2.14
- 1.2.13
- 1.2.12
- 1.2.11
- 1.2.10
- 1.2.9
- 1.2.8
- 1.2.7
- 1.2.6
- 1.2.5
- 1.2.4
- 1.2.3
- 1.2.2
- 1.2.1
- 1.2.0
- 1.1.0
- 1.0.0
- dev-add-catalog-workflow-20241010
- dev-rename-catalog-info-20240923
- dev-add-catalog-info-20240828
- dev-BUGS-7319
- dev-bugs-5651
- dev-hackaton
- dev-cms-639-change-d9-alias
- dev-cms-637-gitlab-infer
- dev-feature/CMS-412-Update-terminus-build-tools-plugin
- dev-cms-374-hosted-bitbucket
- dev-change-d9-alias
- dev-cms-294-cut
- dev-add-ci-from-other-repo
- dev-feature/probot-stale
- dev-version-tool
- dev-add-github-actions-sodium-compat
- dev-ci-from-other-repo
- dev-composer-private-template
- dev-281-update-visit-site-image-path
- dev-project-convert-command
- dev-fix-git-force
- dev-sanitize-url
- dev-session-show-command
- dev-265-ci-watch
- dev-testing-ci
- dev-admin-username-support
- dev-fix-build-step-detection
- dev-delete-ssh-fixtures
- dev-add-interactions
- dev-composer_auth
- dev-build-project-clone
- dev-provider-build-secrets
- dev-bitbucket-pagination
- dev-bitbucket-tokenkey-method
- dev-self-gitlab
- dev-option-for-no-force
- dev-build-providers-json
- dev-readme-gitlab-drupal-support
- dev-fix-github-pr-info
- dev-bitbucket-pipelines
- dev-test-merge
- dev-self-hosted-gitlab
- dev-fix-env-delete
- dev-build-project-repair
- dev-gitlab-project-id
- dev-fix-beta1
- dev-fix-circle-1x
- dev-fix-circle-api
- dev-gitlab-merge-requests
- dev-factor-api
- dev-clone-api
- dev-gitlab-prbranches-fix
- dev-BT-20-paged-api
- dev-gitlab-ci
- dev-simplify-test-script
- dev-delete-unused-envs
- dev-delete-keys
- dev-t2
- dev-paginated-github-responses
- dev-philltran-improved-bitbucket-support
- dev-backport-147
- dev-react-to-pantheon-upstream-yml-1x
- dev-react-to-pantheon-upstream-yml
- dev-json-content-type-for-circle
- dev-terminus-1.8.0
- dev-NickWilde1990-improved-bitbucket-support
- dev-fix-commit-comment
- dev-build-commit-comment-command
- dev-confirm-msg
- dev-prompt-again
- dev-fix-use-statements
- dev-docker-php-ci
- dev-ratelimit-check
- dev-refactor-providers
- dev-better-initial-commit
- dev-refactor-obliterate
- dev-require-closed-pr-1x
- dev-require-closed-pr
- dev-redo-merge-1x
- dev-allow-pr-number
- dev-redo-merge
- dev-merge-via-reset-hard
- dev-strategy-ours
- dev-user-shortcuts
- dev-d7-tests
- dev-bitbucket-provider
- dev-redact-git-push
- dev-LukasRos-bitbucket-provider
- dev-use-tmp-branch-on-merge
- dev-allow-empty-config
- dev-delete-tmp-merge-branch
- dev-autodetect-upstream
- dev-drops-7-support
- dev-ignore-errors-in-changesfile
- dev-refactor-gitprovider
- dev-moar-refactor
- dev-fix-has-remote
- dev-build-assets-in-create-project
- dev-preserve-local-repository
- dev-create-from-dir-master
- dev-create-from-dir
- dev-modern-aliases
- dev-refactor-commandfiles
- dev-create-project-workdir
- dev-add-remote-origin
- dev-prompt-formatting
- dev-export-config-on-install
- dev-consistent-sut
- dev-token-instructions
- dev-php-version-warning
- dev-clone-content
- dev-remove-install
- dev-unnecessary-asign
- dev-create-project
- dev-reuse-multidev
- dev-force-add
This package is auto-updated.
Last update: 2024-10-11 01:11:00 UTC
README
Build Tools is a Terminus Plugin that contains a collection of commands useful for projects making use of an external Git provider and Continuous Integration (CI) along with Pantheon.
Table of Contents
- Project Purpose
- Requirements
- Installation
- Setup
- Available Services
- Commands
- Customization
- Build Tools Command Examples
- Help
- Related Repositories
Project Purpose
The main purposes of the Build Tools project are to:
Ease the creation of new projects making use of an external Git provider, a Continuous Integration service, and Pantheon.
This is primarily done through the build:project:create
commands, which scaffolds new projects from a template repository and performs one-time setup, such as configuring SSH keys and environment variables, needed to connect an external Git provider and CI service with Pantheon. For detailed set-up instructions, see the Terminus Build Tools Guide. To use your own template repository see Customization.
Add additional commands to Terminus to make tasks common in an automated CI workflow easier. See Commands and Build Tools Command Examples for details.
Requirements
- If you are using Terminus 3, you must use the Build Tools
3.x
release. - If you are using Terminus 2, you must use the Build Tools
2.x
release.
PHP 7.2
or greater is recommended.
Installation
Installing Build Tools 3.x:
terminus self:plugin:install terminus-build-tools-plugin
Installing Build Tools 2.x:
mkdir -p ~/.terminus/plugins
composer create-project --no-dev -d ~/.terminus/plugins pantheon-systems/terminus-build-tools-plugin:^2
Note about dev dependencies
The Terminus Build Tools plugin should be installed without dev dependencies. If you install the plugin with a different method, such as cloning this source repository, use composer install --no-dev
to download the project dependencies.
Setup
It is recommended that you use one of the provided example projects as a template when creating a new project. All of the example projects use Terminus 3
and Build Tools 3.x
.
The default template repositories are each assigned an abbreviation, as shown below:
More details about these template repositories see Template Repositories in this document or visit the links above.
You can get started with one of these examples by using the build:project:create
command:
$ terminus build:project:create --team='My Agency Name' wp my-site
This command will create:
- A Pantheon site
- A GitHub repository
- A CircleCI test configuration
It will prompt you for the credentials it needs to create these assets. While GitHub and CircleCI are the defaults, other providers are supported as well. See available services for details.
Note: After running this command, if you get an error "There are no commands defined in the "build:project" namespace", then you may need to install this Terminus plugin first as described in Requirements, above.
Note: 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 be associated with your user and will not have the capability to create multidev environments.
Available Services
The build:project:create
command supports services in the following combination:
Note: if using Github Actions, token should have the "workflow" scope.
Starting a new GitLab Project
$ terminus build:project:create --git=gitlab --team='My Agency Name' wp my-site
Starting a new BitBucket Project
$ terminus build:project:create --git=bitbucket --team='My Agency Name' wp my-site
Starting a new Github/Github Actions Project
$ terminus build:project:create --ci=githubactions --team='My Agency Name' wp my-site
Limitations
Bitbucket
- Composer Lock Updater isn't working quite yet.
Commands
The following commands are available as part of the Build Tools plugin.
build:project:create
The build:project:create
command is used to initialize projects within the Git PR workflow. Automated setup of the Pantheon website along with the corresponding Git and CI provider is included.
Command Options
Additional options are available to further customize the build:project:create
command:
If you want to use a private composer repository, you should provide the credentials like this:
export TERMINUS_BUILD_TOOLS_COMPOSER_AUTH=json_encoded_string
or in ~/.terminus/config.yml file under build-tools.composer-auth.
Then, in the build:project:create command, pass a composer-repository option like this:
terminus build:project:create --template-repository="https://repo.packagist.com/myorg" myorg/myrepo my-project
If you want to use git repository that has not been published to packagist as your template, you should do it like this:
terminus build:project:create --template-repository="git@github.com:myorg/myrepo.git" myorg/myrepo-template my-project
The package name in the composer.json file into the template repo should be "myorg/myrepo-template". If myorg/myrepo is a private repo, you should have access to it in your current terminal.
You can also use the following shorthand:
terminus build:project:create git@github.com:myorg/myrepo.git my-project
and build tools will figure out the right package name for you.
You can find more info about composer repositories, private packages, cli authentication and authentication methods in the official composer documentation.
See terminus help build:project:create
for more information.
build:project:repair
The build:project:repair
command is used to repair projects that were created with the Build Tools plugin. This is useful for rotating credentials, such as provider authentication tokens.
Command Options
Additional options are available to further customize the build:project:repair
command:
build:comment:add:commit
The build:comment:add:commit
command is used to add a comment to a commit on the Git Provider. This is useful in CI scripts for commenting as multidev environments are created or other code feedback is determined.
Either the --message
and/or the --site_url
options are required.
Command Options
Additional options are available to customize the build:comment:add:commit
command:
terminus build:comment:add:pr
The build:comment:add:pr
command is used to add a comment to a pull request on the Git Provider. This is useful in CI scripts for commenting as multidev environments are created or other code feedback is determined.
The --pr_id
option and either the --message
and/or the --site_url
options are required.
Command Options
Additional options are available to customize the build:comment:add:pr
command:
build:credentials:clear
The build:credentials:clear
command is available to clear cached credentials from Build Tools. This is useful when developing Build Tools or trying to remove credentials from a machine.
Command Options
There are no additional options for this command.
build:env:create
The build:env:create
command creates the specified multidev environment on the given Pantheon site from the build assets at the current working directory.
Command Options
By default, this command uses the --force
flag for both git add
and git push
. Passing --no-git-force
will prevent adding this flag but unless your remotes are in sync, it will most likely make the push fail.
build:env:delete:ci
The build:env:delete:ci
command is used to delete multidev environments on Pantheon that match the CI pattern of builds (ci-*
).
Command Options
build:env:delete:pr
The build:env:delete:pr
command is used to delete multidev environments on Pantheon that match the PR pattern of builds (pr-*
) for pull requests (GitHub and BitBucket) or merge requests (GitLab) that have been closed.
Command Options
build:env:install
The build:env:install
command is used to install the CMS on a Pantheon site the specified site.
Command Options
build:env:list
The build:env:list
command is used to list the multidev environments in the specified site.
Command Options
There are no additional options for this command.
build:env:merge
The build:env:merge
command merges a multidev environment in Pantheon into the dev environment.
Command Options
build:env:obliterate
The build:env:obliterate
command deletes a project that was set up through the build:project:create
workflow. This includes the Pantheon site as well as the Git provider repository and the CI provider project.
Note: this is a destructive, irreversible command that should be used with caution.
Command Options
There are no additional command options for this command.
build:env:push
The build:env:push
command pushes code in the current directory to an existing Pantheon site/environment.
Command Options
By default, this command uses the --force
flag for both git add
and git push
. Passing --no-git-force
will prevent adding this flag but unless your remotes are in sync, it will most likely make the push fail.
build:project:info
The build:project:info
command displays information about a site created by the build:project:create
command.
Command Options
There are no additional command options for this command.
build:secrets:delete
The build:secrets:delete
command deletes a secret from Pantheon. These secrets are commonly used for storing information needed by CI integrations, such as Quicksilver Pushback.
Command Options
build:secrets:list
The build:secrets:list
command lists all secret from Pantheon. These secrets are commonly used for storing information needed by future CI integration such as Quicksilver Pushback.
Command Options
build:secrets:set
The build:secrets:set
command sets a secret in a Pantheon. These secrets are commonly used for storing information needed by future CI integration such as Quicksilver Pushback.
Command Options
build:secrets:show
The build:secrets:show
command shows a secret from Pantheon. These secrets are commonly used for storing information needed by CI integrations, such as Quicksilver Pushback.
Command Options
build:workflow:wait
The build:workflow:wait
command waits for a workflow in Pantheon to complete before returning. This is useful when waiting for code to be deployed to a Pantheon environment.
Command Options
build:gitignore:cut
The build:gitignore:cut
command cuts your .gitignore file in the cut line. This is useful before pushing to Pantheon from a source repo.
Customization
You may easily create your own project template by forking one of the Pantheon maintained examples (linked above) and customizing it to suit your needs. To use a custom starter, register your project on Packagist, and then use the projects org/name with the build:project:create
command:
$ terminus build:project:create --team='My Agency Name' my-project/my-starter my-site
See Starter Site Shortcuts below for instructions on defining your own shortcuts for your starter projects.
Configuration
Configuration values for the Terminus Build Tools Plugin may be stored in your Terminus Configuration file, located at ~/.terminus/config.yml
. This is especially useful for agencies who would like every site created within their Pantheon team.
Default Values for Options
Terminus configuration is based on the Robo PHP configuration system. Default option values for Terminus commands can be defined in the same way as other Robo applications. For example, the options for the command build:project:create
are stored in the section command:
> build:
> project:
> create:
> options:
. The example below provides default values for the --admin-password
and --team
options.
command:
build:
project:
create:
options:
admin-password: secret-secret
team: My Pantheon Org
Self-Hosted GitLab
The GitLab URL used by Build Tools can be defined by updating the build-tools:provider:git:gitlab:url
configuration value, as demonstrated by the example below. Note that you will need to replace hostname
with the actual GitLab instance hostname.
build-tools:
provider:
git:
gitlab:
url: hostname
Starter Site Shortcuts
If you often create sites based on certain common starter sites, you may also use your Terminus configuration file to define custom starter site shortcuts. The example below defines shortcuts for the Lightning and Contenta distributions:
command:
build:
project:
create:
shortcuts:
contenta: pantheon-systems/example-drops-8-composer:dev-contenta
Note that the project name follows the standard defined by Composer: org-name
/ project-name
: dev- branch-name
.
Build Customizations
To customize this for a specific project:
- Define necessary environment variables within your CI provider:
- 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.
- 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.
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, configure your CI provider by adding the following environment variable:
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 it is not possible to run multiple tests at the same time. To use the dev
environment, configure your CI provider by adding the following environment variable:
TERMINUS_ENV: dev
** IMPORTANT NOTE: ** If you initially set up your site using terminus build:project:create
, and you do not use the --team
option, or the team you specify is not an Agency organization, then your 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 edit the environment variables in your CI configuration and delete the entry for TERMINUS_ENV
.
Build Tools Command 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; they may be of interest if you are customizing or building your own test scripts.
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 the Dev Environment
terminus build:env:push 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
Commenting on a pull request or merge request
terminus build:comment:add:pr --pr_number=123 --message="Tests passed!"
Help
Run terminus list build
for a complete list of available commands. Use terminus help <command>
to get help on one command.
Related Repositories
Template Repositories
In addition to the Terminus Build Tools Plugin, Pantheon maintains template repositories for:
Each repository includes an opinionated set of workflows and deployment scripts. These templates are meant to be a one-time starting point for new projects and customized as needed. Improvements made over time must be manually applied to existing projects. These are examples, not frameworks.
Build Tools CI Dockerfile
Pantheon maintains a Build Tools CI Dockerfile, which is deployed to quay.io
, for use in Continuous Integration environments. It contains common Pantheon tools, such as Terminus and the Terminus Build Tools plugin. The deployed image tags follow semantic versioning.
Quicksilver Pushback
Quicksilver pushback is a project that makes use of Pantheon's Quicksilver Webhooks to apply code commits made on Pantheon to an external Git provider.