将 TeamCity 与 Perforce 集成

• TeamCity 支持从 Helix Core 2017.1 开始的 Perforce Helix Core 服务器 / 客户端。

• TeamCity 服务器机器上必须安装 Perforce Helix Core 客户端。

• 向 PATH 环境变量中添加 Perforce 客户端的路径。
  或者，可以通过 内部属性teamcity.perforce.customP4Path 设置到 p4 的完整路径。 属性值必须包含 p4 文件名。

为了能够在存储在 Perforce Helix Core 中的项目源码上运行构建，并使用本文中描述的所有功能，您需要执行两个程序：

1. 在 TeamCity 中创建一个专用项目：

   1. 转到 管理 | 项目 并单击 创建项目。
      请注意，这将把项目添加到 根项目下。 或者，您可以将其添加到任何其他现有的项目中。

   2. 输入项目的 Name 和 ID。

   3. 单击 创建。

2. 创建一个 Perforce VCS 根：

   1. 打开 项目设置 ，并导航到 VCS Roots 设置选项卡。

   2. 单击 创建 VCS 根。

   3. 选择 Perforce Helix Core 作为 VCS 类型。

   4. 按照 这篇文章中的说明配置根的设置。

在项目和 Perforce 根配置完成后，您可以继续进行 添加构建配置 并运行构建。

TeamCity可以监控Perforce streams中的提交，并像处理常规 feature branches一样与之进行操作。

如果一个 Perforce root 被配置为使用 Stream 模式，您可以在 root 设置中启用功能分支支持。 在启用后，所有将指定主流作为父级的流都将被包含到由 TeamCity 处理的 功能分支 集合中。 为了只将特定的流包含到此集合中，请编辑分支规范以过滤这些流。 每个过滤规则应从新的一行开始。 语法是 +|-：stream_name。 例如，使用 +：//stream-depot/* 仅监控位于 stream-depot 仓库中的流，其中， * （例如， master ）是逻辑分支名称。 请注意，分支规格中使用的流应为主流的后代。

tip

这里， pipe符号 | 表示 或 命令，如正则表达式中：使用 + 包含，使用 或- 排除。

TeamCity可以处理任务流，但它只有在对任务流进行了非合并提交时才能检测到新的任务流。

如果您在基于 IntelliJ 的 IDE 中编写代码，您可以在将更改提交到主 Perforce 仓库之前预先测试和构建本地修改：请参阅有关 远程运行、 远程调试 和 预测试延迟提交 的常见说明。

远程运行/调试功能对所有类型的 VCS 都很常见，但 Perforce 具有特别的便利性：

• 在 Perforce 流上远程运行构建。

• 在不将其提交到仓库的情况下，测试搁置文件上的更改。

TeamCity 允许您在 Perforce shelved files 上运行个人构建。 这样，您可以在将更改的源文件检入公共仓库之前尝试构建它们。

要在 Perforce shelved 文件上 手动运行 一个自定义构建：

1. 通过单击 运行 按钮旁的上下文菜单，打开 自定义运行对话框。

2. 启用 以个人构建方式运行 选项。

3. 输入包含暂存文件的变更列表的 ID。

   

4. 选择目标 Perforce 根目录。

要为 Perforce shelved 更改列表 配置自动触发：

1. 打开 配置设置 ，并导航到 Triggers 设置选项卡。

2. 添加一个新的 Perforce Shelve Trigger 类型的触发器。

3. 按照 本文 中描述的方式配置其设置。

要使用 TeamCity REST API构建目标搁置的更改列表，请向 /app/rest/buildQueue 端点发送包含以下内容的 POST 请求：

<build>
    <buildType id="Perforce_Swarm_Build"/>
    <properties>
        <property name="teamcity.perforce.build.swarmUpdateUrl" value="{update}"/>
        <property name="vcsRoot.Perforce_Swarm_Root.shelvedChangelist" value="{change}"/>
    </properties>
</build>

{
  "buildType": {
    "id": "Perforce_Swarm_Build"
  },
  "properties": {
    "property": [
      {
        "name": "teamcity.perforce.build.swarmUpdateUrl",
        "value": "{update}"
      },
      {
        "name": "vcsRoot.Perforce_Swarm_Root.shelvedChangelist",
        "value": "{change}"
      }
    ]
  }
}

swarmUpdateUrl

Perforce Helix Swarm 测试更新的 URL。 此属性是可选的，仅由 Helix Swarm 触发的构建使用。

shelvedChangelist

此属性应指向搁置的更改列表编号和有效的 VCS 根外部 ID。 该值应采用 vcsRoot.<external_id>.shelvedChangeList 格式。

除了此端点，您还可以使用 2024.12 版本之前可用的专用 runBuildForShelve 端点：

POST
/app/perforce/runBuildForShelve?buildTypeId=<BUILD_TYPE_ID>&vcsRootId=<VCS_ROOT_ID>&shelvedChangelist=<SHELVED_CHANGELIST_ID>

BUILD_TYPE_ID

您的构建配置的 ID。

VCS_ROOT_ID

相关 VCS 根的外部 ID。

SHELVED_CHANGELIST_ID

所需更改列表的 ID。

为执行与 Perforce 相关的操作，TeamCity 服务器通常在无工作区上下文的情况下执行 Perforce 命令。 例如，对于追踪变更和大多数服务器端操作，工作区并非必需的。 然而，某些情况需要创建一个专用的工作区：

• 默认情况下，TeamCity 使用 代理端检出模式 来检出构建的源代码。 在这种情况下，它会创建一个专用的 Perforce 工作区，并执行相应的 p4 sync 命令来获取源代码。

• 使用 Perforce VCS 根目录来存储 版本化的项目设置。

• 使用 Perforce 流作为功能分支。 在这种情况下，TeamCity 在 Perforce 服务器上创建工作空间，以正确处理任务流。

了解 TeamCity 如何在 Perforce 中创建工作区并在 这篇文章中使用它们。

默认情况下，TeamCity 使用轮询方法来检测 VCS 仓库中的变化。 它定期向 Perforce 服务器发送请求，以检测新的修订版本。 对于拥有数百个 VCS 根的大型安装，这可能会在 Perforce 服务器和 TeamCity 上产生显著的负载。 为了避免后台轮询，您可以在您的 Perforce 服务器上设置一个 post-commit 钩子。 这个钩子会在有更新时通知 TeamCity 开始检查变化。

TeamCity 提供了一个专用的钩子脚本，应保存在您的 Perforce 服务器上。 您可以在此处找到详细的说明 这里。

TeamCity 可以为 Perforce 项目源分配自定义标签。 应用标签及其状态的列表显示在 更改 选项卡的 构建结果 中。

为了配置构建配置的自动标记：

1. 打开 配置设置并导航到 构建功能设置选项卡。

2. 添加 VCS labeling功能。

3. 选择要标记的 Perforce VCS 根。

4. 按照 这里所描述的方式指定标签模式。

个人构建 在处理 Perforce 项目 时，可能会在最终的“撤销个人更改”阶段失败。 如果代码源检出目录在此阶段开始之前变得不可用（例如，当它由 引导构建步骤 挂载并在最后一个构建步骤后自动卸载时），通常会发生这种情况。

在这种情况下，您必须比 TeamCity 通常的操作更早撤销个人更改——在构建步骤仍在运行时。 为此，请在最终构建步骤期间发送以下 服务消息：

##teamcity[undoPersonalPatch]