Phabricator 管理员手册/持续集成

Phabricator 可以配置为支持一些持续集成 (CI) 工作流程，这得益于一个名为 Harbormaster 的组件。

开始阅读官方的 Harbormaster 用户指南，以了解一些重要的通用概念。

你需要什么

1/2 小时
了解 Phabricator 的 Diffusion 组件（处理您的存储库的组件）

安装

Harbormaster 已经是 Phabricator 的一部分，但默认情况下不会显示。它是一个原型应用程序。

查看如何启用原型应用程序

https://secure.phabricator.com/book/phabricator/article/prototypes/

前言

通常，刚开始使用内部持续集成的用户只是想 对提交做出反应并运行命令，但这极其简化，而且可能变得危险。

这就是为什么新的 Phabricator 用户常常惊讶地发现 Phabricator 不允许这种“超级简单”的解决方案。这很好，因为在能够犯大错误之前，我们需要阅读一些文档。

安全问题

首先，不要尝试在您的工作存储库上运行直接命令。永远不要。这可能会破坏该存储库，而且您还可能最终损害整个 Phabricator 基础设施。

花一些时间实施一个标准的干净解决方案，以确保您的存储库安全无虞脚本破坏，并且不以相同的 Phabricator 权限运行这些脚本。例如，在其他机器上运行脚本，在其他工作副本上运行脚本，并且始终使用低权限的临时用户运行脚本，而不是与 Phabricator 相关的用户。

阅读 Drydock 安全官方文档，以获取更多说明。

设置解决方案

为了非常笼统地说，您有两种选择

配置 Phabricator 以连接到一些 SSH 服务器并从那里完成所有操作（克隆、构建等）
将构建委派给其他服务

第一种解决方案很有趣，因为它允许您使用自己的基础设施。这可以通过使用名为 Drydock 的 Phabricator 组件来配置。

第二种解决方案只需调用外部服务的 API。如果您已经拥有构建系统，例如 Jenkins，这将很有趣。

设置 1：在自己的硬件上（使用 Drydock）

您可以配置 Phabricator 的 Harbormaster 组件以使用您自己的硬件构建内容，这得益于一个名为 Drydock 的组件。Drydock 分配您的资源。

以下是实际工作示例的完整流程

开发人员运行 git push 以将本地编辑发布到 Phabricator（或使用 Phabricator 支持的其他源版本控制工具，例如 Subversion 或 Mercurial）
Phabricator 检查该提交是否触发了规则，并最终执行操作。Herald 组件定义了这些规则。
匹配了一个 Herald 规则，并且操作是在 Harbormaster 中配置的“构建计划”。它开始执行其步骤。
构建计划的第一个步骤可能是请求一个工作副本（我们说，我们“租用”一个工作副本——因为我们不直接处理 Diffusion 使用的相同存储库，而只是获取或创建另一个副本）
Drydock 组件提供该工作副本，检查是否有可用的主机具有已准备好的工作副本。它通过您配置的 Almanac 目录了解您的配置基础设施。
构建计划的下一步可以是“在该工作副本上运行命令”（从技术上讲，它在“Drydock 租用”上运行命令）
如果命令成功退出，您将在您的提交旁边看到一个 已通过 标记，否则将看到 已失败 标记。

让我们开始实施它。

我们首先建议您阅读来自 Phabricator 讨论论坛的这个示例配置。

描述您的网络和设备

首先，您需要在 Almanac 目录中描述一些设备。

我们所说的“设备”是什么

一个可以通过 SSH 访问的物理服务器
一个虚拟服务器（VPS、Docker 运行、虚拟机等），可以通过 SSH 访问

您知道您要为构建系统专门分配哪种设备。它可能是一个虚拟服务器，也可能恰好是您的同一台服务器（但使用低权限的用户）。

现在，让我们在您的 Almanac 目录中对其进行描述：^[1]

定义一个 Almanac 网络：您必须至少有一个网络。常见的名称是“公共”或“私有”或“本地网络”。您的服务器将与之关联。
定义一个 Almanac 设备：为要为构建系统专门分配的第一台服务器指定一个名称。该服务器应可以通过 SSH 从 Phabricator 访问，因此请单击 添加接口，选择之前的网络，插入其 IP 地址/域名，然后键入标准 SSH 端口 22。
定义一个 Almanac 服务：打开 Almanac 并定义一个服务，选择 Drydock：资源池 作为服务类型。这将是可用服务器的容器，因此名称可以是“构建服务器池”。单击“添加绑定”并选择之前的设备。

准备您的构建服务器

此时，您应该已经确定好要用于构建系统的服务器。您应该知道如何通过 SSH 连接到该服务器（如果不知道，请阅读 SSH 手册）。

确保您可以使用 SSH 公钥连接到您的服务器（提示：为此目的创建一个额外的 SSH 密钥，因为您需要将相关的私钥发布到 Phabricator 中，以允许它连接到您的服务器）。

ssh foobot@server_build_01

进入您的服务器后，确保您有权克隆您的仓库。尝试克隆您的仓库之一。如果您的仓库是公开的，那么您就可以正常操作。相反，如果您的仓库受到一些可见性限制，则应该创建一个专门的 Phabricator 机器人（机器人是类型为“机器人”的用户）并将该用户放在正确的项目中。您可以从 Phabricator 用户页面创建机器人。例如，机器人可以被称为“Foo Bot @ server_build_01”，您必须将其添加到正确的项目中，以允许该用户读取您的仓库。

您可能希望从服务器生成一个 SSH 密钥，并在其用户首选项（您刚刚创建的机器人的用户首选项）中发布其公钥。简而言之，确保您可以从您选择的用户（foobot）使用标准的 Phabricator 授权从您的服务器克隆您的仓库。

提示：实际上，您选择的用户（foobot）应该能够写入 /var/drydock 目录以克隆工作副本。^[2]

从 Drydock 主机文档中了解更多信息。

设置 Drydock 蓝图

现在您应该定义几个“蓝图”。蓝图是 Drydock 组件要达成的“目标”。请先阅读 Drydock 蓝图文档。

简而言之，您需要配置两个 Drydock 蓝图：^[3]

创建一个类型为 Almanac 主机 的蓝图 - 此蓝图将选择可用的主机，因此示例名称可以是“主机租用器”。在 Almanac 服务 字段中，选择您创建的服务（可能称为“Buildservers 池”）。请记住设置一个有效的 SSH 公钥以访问主机，如 #准备您的构建服务器中所述。
创建一个类型为 工作副本 的蓝图 - 此蓝图将提供工作副本，因此示例名称可以是“来自 Buildservers 池的工作副本租用器”。在 使用蓝图 字段中，选择之前创建的蓝图（可能称为“主机租用器”）。

现在从 Phabricator 的根目录运行此命令

./bin/drydock lease --type host

您应该会看到类似的输出

$ ./bin/drydock lease --type host
Queued lease for activation:

        https://example.com/drydock/lease/1/

Waiting for daemons to activate lease...
<Lease Queued> Lease queued for acquisition.
<Lease Acquired> Lease acquired.
<Lease Activated> Lease activated.
Activation complete. This lease is permanent until manually released with:

        $ ./bin/drydock release-lease --id 1

Lease activated in 2,277ms.

您可以进一步阅读 Drydock 工作副本官方文档以获取更多说明。

设置 Harbormaster 构建计划

现在进入 Harbormaster 页面，然后单击“创建构建计划”^[4]。

添加两个构建步骤

创建一个类型为 租用工作副本 的构建步骤。在 使用蓝图 字段中，选择之前创建的 Drydock 工作副本蓝图（可能称为“来自 Buildservers 池的工作副本租用器”）。示例名称可以是“从 Buildservers 池租用工作副本”。工件名称 是此步骤产生的内容，因此示例名称可以是“从 Buildservers 池租用的工作副本”。
创建一个类型为 Drydock：运行命令 的构建步骤。在 Drydock 租用 字段中，输入与上一步的 工件名称 字段中输入的值相同的值（可能称为“从 Buildservers 池租用的工作副本”。在命令字段中，键入将在您的仓库中运行的命令。

提示：命令的工作目录将是工作副本的路径名。您不应该尝试预测其完整的路径名，因为它是在内部生成的。

提示：工作副本将克隆到 /var/drydock^[2] 中。

提示：该命令将以您在 #准备您的构建服务器中准备的 SSH 用户的权限执行。

在事件之后运行构建计划

另请参阅：Phabricator 管理员手册/Herald

现在您可能希望配置 Phabricator 在事件之后自动运行构建计划。例如

在受信任的用户在仓库中提交代码后运行构建计划 - 请参阅 #设置 Herald 以对提交进行反应
在不受信任的用户发送或修改代码评审补丁后运行构建计划 - 请参阅 #设置 Herald 以对 Differential 修订进行反应

设置 Herald 以对提交进行反应

您可能希望在有人对仓库进行提交时自动运行构建计划。在这种情况下

打开 Herald 组件的主页，然后单击 创建 Herald 规则^[5]
选择 新建规则目标：提交
选择 规则类型：对象 - 为了将您的 Herald 规则附加到特定的仓库
键入您的仓库代码 - 请注意，它以大写的 R 开头，类似于 R123^[6]
在条件字段中，您可能希望选择始终
在操作字段中，您可能希望添加 运行构建计划 并选择您的构建计划。

设置 Herald 以对 Differential 修订进行反应

您可能希望在有人从 Differential 提出补丁时自动运行构建计划。

在 Phabricator 中，用户可以为仓库提出补丁（Differential 修订）。用户可以使用名为 Arcanist 的命令行工具（使用命令 arc diff）提交此补丁。然后，您可能希望检查此补丁在合并（落地）到您的仓库后是否会破坏一切。

此方法的问题在于，您无法在这种情况下运行构建计划。事实上，此时您还没有包含该补丁的仓库。

这就是为什么此解决方案类似于 #设置 Herald 以对提交进行反应，但我们需要引入一个 暂存区。

以下是步骤

创建一个新的仓库（它可以位于 Diffusion 中，也可以不在 Diffusion 中），并确保普通用户有权向其中推送代码。这将是您的 暂存区。
现在返回到您的原始仓库，并打开其 Diffusion 页面。编辑它，您应该会注意到一个 暂存区 菜单。从该页面粘贴您的新仓库的 URL^[7]
打开 Herald 组件的主页，然后单击 创建 Herald 规则^[5]
选择 新建规则目标：Differential 修订
选择 规则类型：全局
在“条件”字段中，您可能需要选择“存储库项目”，并选择“包含任何”选项，然后选择您的项目。
在操作字段中，您可能希望添加 运行构建计划 并选择您的构建计划。

另请参阅官方Harbormaster文档中关于“手动暂存区”的“更改移交”部分。

方案 2：使用外部服务

另一种常见解决方案是使用 Phabricator 之外的外部构建服务。如果您已经熟悉外部构建服务，此解决方案可能会更好。

请注意，在调用外部服务时，Phabricator 可能无法等待输出（因为 Phabricator 向您的外部服务发送 HTTP 请求，但显然该服务不会在该短请求结束时结束构建）。因此，您可能还需要配置另一个小型守护程序来查询您的外部服务，等待您的构建，并最终通知 Phabricator 该构建状态。

一些不完全的资源列表

Jenkins 和 Phabricator 集成

故障排除

以下是您在实施 #方案 1：在自己的硬件上使用 Drydock 后可能会看到的一些常见错误。

故障排除“租赁 PHID-... 从未激活”

如果您看到错误“租赁 PHID-... 从未激活”或类似的堆栈跟踪

PhabricatorWorkerPermanentFailureException: Lease "PHID-..." never activated. in .../phabricator/src/applications/harbormaster/step/HarbormasterLeaseWorkingCopyBuildStepImplementation.php:91
Stack trace:
#0 .../phabricator/src/applications/harbormaster/worker/HarbormasterTargetWorker.php(70): HarbormasterLeaseWorkingCopyBuildStepImplementation->execute(Object(HarbormasterBuild), Object(HarbormasterBuildTarget))
#1 .../phabricator/src/infrastructure/daemon/workers/PhabricatorWorker.php(124): HarbormasterTargetWorker->doWork()
#2 .../phabricator/src/infrastructure/daemon/workers/storage/PhabricatorWorkerActiveTask.php(158): PhabricatorWorker->executeTask()
#3 .../phabricator/src/infrastructure/daemon/workers/PhabricatorTaskmasterDaemon.php(22): PhabricatorWorkerActiveTask->executeTask()
#4 .../libphutil/src/daemon/PhutilDaemon.php(219): PhabricatorTaskmasterDaemon->run()
#5 .../libphutil/scripts/daemon/exec/exec_daemon.php(131): PhutilDaemon->execute()
#6 {main}

再次检查 #设置 Drydock 蓝图并查看您的蓝图日志。您可能尚未激活任何主机。

故障排除“资源激活失败：[CommandException] 命令失败，错误代码为 #128！”

如果您看到此错误或类似的错误

Resource activation failed: [CommandException] Command failed with error #128!
COMMAND
ssh '-o' 'LogLevel=ERROR' '-o' 'StrictHostKeyChecking=no' '-o' 'UserKnownHostsFile=/dev/null' '-o' 'BatchMode=yes' -l ...

STDOUT
(empty)

STDERR
LOT OF ERRORS HERE

仔细查看 STDERR 部分

故障排除“无法创建目录 .ssh”

如果您有

无法创建目录“.../.ssh”

这意味着 Phabricator 用户守护进程正在尝试使用 SSH 连接到您的构建服务器，因此它需要一个可写的 $HOME/.ssh 目录来写入 $HOME/.ssh/known_hosts 文件等。Phabricator 用户守护进程的主目录可能不可写。

如果您不知道您的 Phabricator 用户守护进程是什么，它是运行您的守护进程的守护进程。您在安装过程中设置了它。

故障排除“无法创建 /var/drydock 的前导目录”

如果您有

could not create leading directories of '/var/drydock/...': Permission denied

构建内容的用户无法写入 /var/drydock，或者该路径不存在。请再次阅读 #准备您的构建服务器部分。请注意，该路径实际上是无法自定义的。^[8]

故障排除“致命错误：无法从远程存储库读取”

如果您有

fatal: Could not read from remote repository. Please make sure you have the correct access rights and the repository exists.

返回到 #准备您的构建服务器部分。登录到您的构建服务器并尝试从其中克隆存储库。您可能需要在 Phabricator 中使用专门的机器人帐户授权服务器用户，并配置 SSH 密钥。

备注

↑ 在 Phabricator 搜索框中搜索“Almanac”，或访问 example.com/almanac/，可以找到 Almanac 库存。
↑ ^a ^b 实际上，Drydock 被硬编码为写入 /var/drydock 中。有关更多详细信息，请参阅 T10664 和 T9492。
↑ 在 Phabricator 搜索框中搜索“Drydock”，或访问 example.com/drydock/，可以找到 Drydock 页面。
↑ 在 Phabricator 搜索框中搜索“Harbormaster”，然后单击“构建计划”，或访问 example.com/harbormaster/plan/，可以找到构建计划。
↑ ^a ^b 在 Phabricator 搜索框中搜索“Herald”，或访问 example.com/herald/，可以找到 Herald 组件。
↑ "Herald rule of type object for repository uppercase "R"". Phabricator Discussion Forum.
↑ 您可以通过访问 Diffusion 存储库的公共页面，然后单击“管理存储库”→“暂存区”，或访问 example.com/source/REPO_NAME/manage/staging/，来访问该存储库的“暂存区”。
↑ "Can an alternate drydock (something other than /var/drydock) area be configuable". {{cite web}}: Unknown parameter |published= ignored (help)

[1] 在 Phabricator 搜索框中搜索“Almanac”，或访问 example.com/almanac/，可以找到 Almanac 库存。

[drydock-path-hardcoded-2] 实际上，Drydock 被硬编码为写入 /var/drydock 中。有关更多详细信息，请参阅 T10664 和 T9492。

[3] 在 Phabricator 搜索框中搜索“Drydock”，或访问 example.com/drydock/，可以找到 Drydock 页面。

[4] 在 Phabricator 搜索框中搜索“Harbormaster”，然后单击“构建计划”，或访问 example.com/harbormaster/plan/，可以找到构建计划。

[where-herald-5] 在 Phabricator 搜索框中搜索“Herald”，或访问 example.com/herald/，可以找到 Herald 组件。

[6] "Herald rule of type object for repository uppercase "R"". Phabricator Discussion Forum.

[7] 您可以通过访问 Diffusion 存储库的公共页面，然后单击“管理存储库”→“暂存区”，或访问 example.com/source/REPO_NAME/manage/staging/，来访问该存储库的“暂存区”。

[8] "Can an alternate drydock (something other than /var/drydock) area be configuable". {{cite web}}: Unknown parameter |published= ignored (help)

[1]