README

构建工具是一个包含了一系列命令的Terminus插件，这些命令对于使用外部Git提供程序、持续集成（CI）以及Pantheon的项目非常有用。

目录

1. 项目目的
2. 要求
3. 安装
4. 设置
5. 可用服务
6. 命令
7. 自定义
8. 构建工具命令示例
9. 帮助
10. 相关仓库

项目目的

构建工具项目的主要目的是

简化使用外部Git提供程序、持续集成服务以及Pantheon创建新项目的流程。这主要通过build:project:create命令实现，它从模板仓库生成新项目，并执行一次性的设置，例如配置SSH密钥和环境变量，以便将外部Git提供程序和CI服务与Pantheon连接。有关详细的设置说明，请参阅Terminus构建工具指南。若要使用自己的模板仓库，请参阅自定义。

为Terminus添加额外的命令，以便在自动化CI工作流程中简化常见的任务。有关详细信息，请参阅命令和构建工具命令示例。

要求

• 如果您正在使用Terminus 2，您必须使用Build Tools 2.x版本。
• 如果您正在使用Terminus 1，您必须使用Build Tools 1.x版本。请注意，Terminus 1即将达到生命周期的结束，建议使用版本2。

建议使用PHP 7.2或更高版本。

安装

安装Build Tools 2.x

mkdir -p ~/.terminus/plugins
composer create-project --no-dev -d ~/.terminus/plugins pantheon-systems/terminus-build-tools-plugin:^2.0.0-beta17

安装Build Tools 1.x

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

关于开发依赖的说明

建议您在不包含开发依赖的情况下安装Terminus构建工具插件。如果您使用其他方法安装插件，例如克隆此源代码仓库，请使用composer install --no-dev下载项目依赖。

设置

建议您在创建新项目时使用提供的示例项目之一作为模板。所有示例项目都使用Terminus 2和Build Tools 2.x。

默认模板仓库各自分配了一个缩写，如下所示

• WordPress: wp
• Drupal 8: d8
• Drupal 7: d7

有关这些模板仓库的更多详细信息，请参阅本文件中的模板仓库或访问上面的链接。

您可以通过使用build:project:create命令开始使用这些示例之一

$ terminus build:project:create --team='My Agency Name' wp my-site

此命令将创建

• Pantheon站点
• 一个GitHub仓库
• 一个CircleCI测试配置

它将提示您输入创建这些资源所需的凭据。虽然GitHub和CircleCI是默认设置，但也支持其他提供商。请参阅可用服务以获取详细信息。

注意：运行此命令后，如果您收到错误“在"build:project"命名空间中未定义任何命令”，则您可能需要先按照要求部分中所述安装此Terminus插件。

注意：通过--team选项指定您的机构组织名称非常重要。如果您不这样做，则新站点将与您的用户关联，并且无法创建多开发环境。

可用服务

build:project:create命令支持以下组合的服务

开始一个新的GitLab项目

$ terminus build:project:create --git=gitlab --team='My Agency Name' wp my-site

开始一个新的BitBucket项目

$ terminus build:project:create --git=bitbucket --team='My Agency Name' wp my-site

限制

Bitbucket

• Composer Lock更新器目前尚未正常工作。

命令

以下命令是Build Tools插件的一部分。

build:project:create

build:project:create命令用于在Git PR工作流程中初始化项目。包括自动设置Pantheon网站以及相应的Git和CI提供商。

命令选项

有其他选项可以进一步自定义build:project:create命令

有关更多信息，请参阅terminus help build:project:create。

build:project:repair

build:project:repair命令用于修复使用Build Tools插件创建的项目。这对于轮换凭据，如提供商身份验证令牌非常有用。

命令选项

有其他选项可以进一步自定义build:project:repair命令

build:comment:add:commit

build:comment:add:commit命令用于向Git提供商上的提交添加注释。这在CI脚本中很有用，可以在创建多开发环境或其他代码反馈时进行注释。

需要--message和/或--site_url选项。

命令选项

有其他选项可以自定义build:comment:add:commit命令

terminus build:comment:add:pr

build:comment:add:pr命令用于向Git提供商上的拉取请求添加注释。这在CI脚本中很有用，可以在创建多开发环境或其他代码反馈时进行注释。

需要--pr_id选项和--message和/或--site_url选项。

命令选项

有其他选项可以自定义build:comment:add:pr命令

build:credentials:clear

build:credentials:clear命令可用于清除Build Tools中的缓存的凭据。这在开发Build Tools或尝试从计算机中删除凭据时非常有用。

命令选项

此命令没有其他选项。

build:env:create

build:env:create命令从当前工作目录的构建资产创建指定Pantheon站点上的指定多开发环境。

命令选项

build:env:delete:ci

build:env:delete:ci命令用于删除匹配构建模式（ci-*）的Pantheon上的多开发环境。

命令选项

build:env:delete:pr

build:env:delete:pr命令用于删除匹配拉取请求模式（pr-*）的Pantheon上的多开发环境，这些拉取请求（GitHub和BitBucket）或合并请求（GitLab）已被关闭。

命令选项

build:env:install

build:env:install命令用于在指定的Pantheon站点上安装CMS。

命令选项

build:env:list

build:env:list命令用于列出指定站点中的多开发环境。

命令选项

此命令没有其他选项。

build:env:merge

build:env:merge 命令将 Pantheon 中的多开发环境合并到开发环境中。

命令选项

build:env:obliterate

build:env:obliterate 命令会删除通过 build:project:create 工作流程设置的工程。这包括 Pantheon 站点以及 Git 提供商的仓库和 CI 提供商的工程。

注意：这是一个具有破坏性的、不可逆的命令，应谨慎使用。

命令选项

此命令没有额外的命令选项。

build:env:push

build:env:push 命令将当前目录中的代码推送到现有的 Pantheon 站点/环境。

命令选项

build:project:info

build:project:info 命令显示由 build:project:create 命令创建的站点的信息。

命令选项

此命令没有额外的命令选项。

build:secrets:delete

build:secrets:delete 命令从 Pantheon 中删除一个秘密。这些秘密通常用于存储 CI 集成所需的信息，例如 Quicksilver Pushback。

命令选项

build:secrets:list

build:secrets:list 命令列出 Pantheon 中的所有秘密。这些秘密通常用于存储 CI 集成所需的信息，例如 Quicksilver Pushback。

命令选项

build:secrets:set

build:secrets:set 命令在 Pantheon 中设置一个秘密。这些秘密通常用于存储 CI 集成所需的信息，例如 Quicksilver Pushback。

命令选项

build:secrets:show

build:secrets:show 命令显示 Pantheon 中的秘密。这些秘密通常用于存储 CI 集成所需的信息，例如 Quicksilver Pushback。

命令选项

build:workflow:wait

build:workflow:wait 命令在返回之前等待 Pantheon 中的工作流程完成。当等待代码部署到 Pantheon 环境时非常有用。

命令选项

自定义

您可以通过分支 Pantheon 维护的示例之一（如上所示）并对其进行自定义以满足您的需求，轻松地创建自己的项目模板。要使用自定义启动器，请在 Packagist 上注册您的项目，然后使用 build:project:create 命令中的 projects org/name

$ terminus build:project:create --team='My Agency Name' my-project/my-starter my-site

有关为您的启动项目定义自己的快捷方式的说明，请参阅下面的 启动站点快捷方式。

配置

Terminus Build Tools 插件的配置值可以存储在位于 ~/.terminus/config.yml 的 Terminus 配置文件中。这对于希望在其 Pantheon 团队内创建每个站点的代理机构特别有用。

选项的默认值

Terminus 配置基于 Robo PHP 配置系统。默认选项值可以像其他 Robo 应用程序一样定义。例如，build:project:create 命令的选项存储在 command: > build: > project: > create: > options: 部分。以下示例提供了 --admin-password 和 --team 选项的默认值。

command:
  build:
    project:
      create:
        options:
          admin-password: secret-secret
          team: My Pantheon Org

自托管的 GitLab

Build Tools 使用的 GitLab URL 可以通过更新以下配置值来定义，如下例所示。请注意，您需要将 hostname 替换为实际的 GitLab 实例主机名。

build-tools:
  provider:
    git:
      gitlab:
        url: hostname

启动站点快捷方式

如果您经常基于某些常见的启动站点创建站点，您也可以使用您的 Terminus 配置文件来定义自定义启动站点快捷方式。以下示例定义了 Lightning 和 Contenta 分发的快捷方式

command:
  build:
    project:
      create:
        shortcuts:
          contenta: pantheon-systems/example-drops-8-composer:dev-contenta

请注意，项目名称遵循 Composer 的标准： org-name / project-name : dev- branch-name。

构建自定义

为了针对特定项目进行自定义

• 在您的 CI 提供商中定义必要的环境变量
  • TERMINUS_SITE：测试中使用的Pantheon站点的名称。
  • TERMINUS_TOKEN：一个具有对由TERMINUS_SITE指定的terminus站点的写访问权限的Terminus OAuth令牌。
  • GIT_EMAIL：用于配置我们提交时使用的git用户的电子邮件地址。
• 根据需要自定义dependencies:以安装额外的工具。
• 将示例test:部分替换为您要运行的测试命令。
• 将build-assets脚本添加到您的composer.json文件中。[链接](https://pantheon.io/blog/writing-composer-scripts)

PR环境与其他测试环境

请注意，每个PR使用单个环境意味着无法同时针对同一PR运行多个测试。目前，没有取消正在运行测试的努力；如果在新提交推送到PR分支之前没有取消并发构建，那么两个测试可能会相互冲突。如果希望在同一PR上支持并行测试，则可以消除PR环境，并使所有测试都在其独立的CI环境中运行。为此，通过添加以下环境变量来配置您的CI提供程序：

    TERMINUS_ENV: $CI_LABEL

在没有Multidevs的情况下运行测试

要在此没有Multidev环境支持支持的Pantheon站点上使用此工具，可以针对dev环境运行所有测试。如果这样做，则无法同时运行多个测试。要使用dev环境，通过添加以下环境变量来配置您的CI提供程序：

    TERMINUS_ENV: dev

**重要说明：** 如果您最初使用terminus build:project:create设置您的站点，并且您没有使用--team选项，或者您指定的团队不是代理组织，则您的配置将自动设置为仅使用dev环境。如果您以后向您的站点添加Multidev功能，则需要在您的CI配置中编辑环境变量并删除TERMINUS_ENV的条目。

构建工具命令示例

以下示例显示了如何在测试脚本中使用一些其他build:env:命令。通常不需要直接运行这些命令；如果您正在自定义或构建自己的测试脚本，则它们可能很有趣。

创建测试Multidev

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

此命令将提交生成的工件到一个新分支，然后为测试创建请求的multidev环境。

将代码推送到开发环境

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

此命令将提交生成的工件到现有的multidev环境或开发环境。

将测试Multidev合并到开发环境

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

删除测试Multidevs

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

列出测试Multidevs

terminus build:env:list

在拉取请求或合并请求中评论

terminus build:comment:add:pr --pr_number=123 --message="Behat测试通过！"

帮助

运行terminus list build获取可用命令的完整列表。使用terminus help <command>获取有关单个命令的帮助。

相关仓库

模板仓库

除了Terminus Build Tools插件之外，Pantheon还维护以下模板仓库：

• WordPress
• Drupal 8
• Drupal 7

每个仓库都包含一组有见地的流程和部署脚本。这些模板旨在作为新项目的单次起点，并根据需要定制。随着时间的推移做出的改进必须手动应用于现有项目。这些都是示例，不是框架。

构建工具CI Dockerfile

潘多拉系统维护了一个构建工具CI Dockerfile，该文件部署到了quay.io，用于持续集成环境。它包含常见的潘多拉工具，如Terminus和Terminus构建工具插件。部署的镜像标签遵循语义化版本。

Quicksilver推回

Quicksilver推回是一个项目，它利用潘多拉的Quicksilver Webhooks将潘多拉上做出的代码提交应用到外部的Git服务提供商。