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 Build Tools 指南。要使用自己的模板仓库，请参阅 自定义。

向 Terminus 添加额外的命令，以使在自动 CI 工作流中常见的任务更容易执行。 有关详细信息，请参阅 命令 和 构建工具命令示例。

要求

• 如果您正在使用 Terminus 3，则必须使用 构建工具 3.x 版本。
• 如果您正在使用 Terminus 2，则必须使用 构建工具 2.x 版本。

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

安装

安装构建工具 3.x

terminus self:plugin:install terminus-build-tools-plugin

安装构建工具 2.x

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

关于开发依赖项的说明

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

设置

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

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

• WordPress: wp
• Drupal 9: d9
• 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命令支持以下组合的服务

注意：如果使用Github Actions，则令牌应具有"workflow"权限。

启动新的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

启动新的Github/Github Actions项目

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

限制

Bitbucket

• Composer Lock Updater尚不能正常工作。

命令

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

build:project:create

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

命令选项

还有其他选项可用于进一步自定义build:project:create命令。

如果您想使用私有composer存储库，您应该提供以下凭据：

export TERMINUS_BUILD_TOOLS_COMPOSER_AUTH=json_encoded_string

或者在~/.terminus/config.yml文件下的build-tools.composer-auth中。

然后，在build:project:create命令中，传递一个类似这样的composer-repository选项：

terminus build:project:create --template-repository="https://repo.packagist.com/myorg" myorg/myrepo my-project

如果您想使用尚未发布到packagist的git仓库作为模板，您应该这样做：

terminus build:project:create --template-repository="git@github.com:myorg/myrepo.git" myorg/myrepo-template my-project

在composer.json文件中的模板仓库中的包名称应为"myorg/myrepo-template"。如果myorg/myrepo是私有仓库，您应该能在当前终端中访问它。

您还可以使用以下缩写：

terminus build:project:create git@github.com:myorg/myrepo.git my-project

然后构建工具将为您找出正确的包名。

您可以在官方composer文档中找到有关composer存储库、私有包、CLI身份验证和身份验证方法的更多信息。

有关更多信息，请参阅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 提供商的 pull request 中添加注释。这在创建多开发环境或确定其他代码反馈时在 CI 脚本中很有用。

需要使用 --pr_id 选项以及 --message 和/或 --site_url 选项。

命令选项

还可以使用其他选项来自定义 build:comment:add:pr 命令。

build:credentials:clear

build:credentials:clear 命令可用于从构建工具中清除缓存凭据。这在开发构建工具或尝试从计算机中删除凭据时很有用。

命令选项

此命令没有其他选项。

build:env:create

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

命令选项

默认情况下，此命令使用 --force 标志对 git add 和 git push。传递 --no-git-force 将防止添加此标志，但除非您的远程同步，否则很可能会使推送失败。

build:env:delete:ci

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

命令选项

build:env:delete:pr

build:env:delete:pr 命令用于删除与 pull request 的 PR 模式（pr-*）匹配的 Pantheon 上的多开发环境，这些 pull request（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 站点/环境。

命令选项

默认情况下，此命令使用 --force 标志对 git add 和 git push。传递 --no-git-force 将防止添加此标志，但除非您的远程同步，否则很可能会使推送失败。

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 环境时很有用。

命令选项

构建：gitignore：裁剪

build:gitignore:cut 命令会在裁剪行处裁剪您的 .gitignore 文件。在将内容推送到 Pantheon 的源仓库之前，这非常有用。

自定义

您可以通过分支上述 Pantheon 维护的示例之一并自定义以满足您的需求，轻松创建自己的项目模板。要使用自定义启动器，请在 Packagist 上注册您的项目，然后使用 build:project:create 命令与项目的 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 应用程序一样，可以在相同的方式下定义 Terminus 命令的默认选项值。例如，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 可以通过更新以下配置值 build-tools:provider:git: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 OAuth 令牌，它对指定的 terminus 站点具有写访问权限。
  • GIT_EMAIL：用于配置我们提交的 git 用户的电子邮件地址。
• 根据需要自定义 dependencies: 以安装额外的工具。
• 用运行您测试的命令替换示例 test: 部分。
• 将 build-assets 脚本 添加到您的 composer.json 文件中。

PR 环境与其他测试环境

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

    TERMINUS_ENV: $CI_LABEL

在没有多开发环境的情况下运行测试

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

    TERMINUS_ENV: dev

**重要提示：** 如果你最初使用 terminus build:project:create 设置你的网站，并且你没有使用 --team 选项，或者你指定的团队不是机构组织，那么你的配置将自动设置为仅使用开发环境。如果你以后为网站添加多环境功能，你将需要编辑CI配置中的环境变量，并**删除** TERMINUS_ENV 的条目。

构建工具命令示例

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

创建测试多环境

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

此命令将提交生成的工件到新的分支，并创建请求的多环境以用于测试。

将代码推送到开发环境

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

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

将测试多环境合并到开发环境

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

删除测试多环境

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

列出测试多环境

terminus build:env:list

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

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

帮助

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

相关仓库

模板仓库

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

• WordPress
• Drupal 9
• Drupal 8
• Drupal 7

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

构建工具CI Dockerfile

Pantheon维护了一个Build Tools CI Dockerfile，该文件部署到quay.io，用于持续集成环境。它包含常见的Pantheon工具，如Terminus和Terminus Build Tools插件。部署的镜像标签遵循语义版本控制。

Quicksilver Pushback

Quicksilver pushback 是一个项目，它利用Pantheon的 Quicksilver Webhooks 将在Pantheon上做出的代码提交应用到外部Git提供者。