提交状态发布器

提交状态发布器是一个构建功能，用于将构建状态发布到 VCS 提供方。这样可让您在仓库页面跟踪代码健康状况，并快速跳转到相关 TeamCity 构建以查看详细构建日志。

支持的 VCS 提供方：

GitHub （也支持拉取请求的构建状态）
GitLab
Azure DevOps （支持的状态：Pending、Succeeded、Failed、Error）
Bitbucket Server 和 Bitbucket Cloud
JetBrains Space
JetBrains Upsource
Gerrit Code Review 工具 2.6+
Perforce Helix Swarm

对于 GitHub、GitLab、Space、Bitbucket 服务器和 Bitbucket Cloud、Perforce Helix Swarm 以及 Azure DevOps，提交状态发布器会在构建被添加到队列时立即更新版本控制系统中的提交状态，提供最新信息。

通用设置

VCS root（VCS 根）

执行所有 TeamCity 与 VCS 通信操作的 VCS 根。这可以是一个独立的 VCS 根，或构建配置/流水线已用于检出仓库文件的 VCS 根。

发布者

您的 VCS 类型。其他提交状态发布器设置会因该设置而有所不同。

服务器 URL

您的 VCS 服务器的 URL。公有服务请使用默认值，本地解决方案请输入自定义 URL。例如，GitHub.com 使用 https://api.github.com ，GitHub Enterprise 使用 http[s]://<主机>[:<端口>]/api/v3。

认证设置

这些设置指定提交状态发布器在发布构建状态之前应如何认证到您的 VCS。您可以在对话框底部点击测试连接按钮，验证当前设置是否有效。

对于大多数 VCS 提供方，您有以下选项：

密码 — 传统的用户名/密码凭据对。请注意，大多数提供方已逐步弃用此认证方式，因为安全性较低。
访问令牌 — 使用需在 VCS 端手动生成的个人访问令牌进行认证。对于某些提供方（例如 GitHub），可以点击魔棒按钮，让 TeamCity 通过预先配置的 OAuth 连接自动获取访问令牌：
否则，请手动生成具有正确权限的访问令牌。例如，GitHub：
- 经典 GitHub 令牌：公共仓库可用 public_repo 和 repo:status ；私有仓库可用 仓库。另请参阅： OAuth 应用的作用域。
- 精细化令牌：请添加具有“Read and write”访问类型的 Commit Statuses 权限。该权限仅可添加到“所有仓库”或“仅选择的仓库”访问类型的令牌。另请参阅：精细化个人访问令牌所需权限。
可刷新访问令牌 — 使用 TeamCity 通过现有 OAuth/应用连接从指定 VCS 提供方获取的短期令牌（区别于用户在 VCS 托管端手动生成的 static PAT 令牌）。有关生成和使用可刷新令牌的更多信息，请参阅以下文章：管理可刷新访问令牌。
使用 VCS 根证书 — TeamCity 将尝试从 VCS 根设置中提取凭据。这个选项是为使用令牌（无论是静态/个人还是可刷新/OAuth）通过身份验证并使用HTTP(S)获取URL来获取仓库的VCS根设计的。如果相关的 VCS 根使用匿名或标准的用户名-密码认证，或者使用 SSH 获取 URL，请选择其他选项。

构建名称

将在状态消息中显示的自定义构建名称。允许包含 ％\参数名称％ 参数引用。例如，概览部分的图片显示了使用以下自定义构建名称生成的状态信息：

Integration tests (build #%build.number%, %teamcity.agent.jvm.os.name%)

此设置适用于所有基于 Git 的提供方：Azure DevOps、Bitbucket Cloud、Bitbucket 服务器和 Data Center、GitHub（“状态检查名称”设置）、GitLab（“外部作业名称”）以及 JetBrains Space（“显示名称”）。

特定供应商的配置

GitHub

使用手动生成的访问令牌时，务必确保权限充足：

经典 GitHub 令牌：公共仓库可用 public_repo 和 repo:status ；私有仓库可用 仓库。另请参阅： OAuth 应用的作用域。
精细化令牌：请添加具有“Read and write”访问类型的 Commit Statuses 权限。该权限仅可添加到“所有仓库”或“仅选择的仓库”访问类型的令牌。另请参阅：精细化个人访问令牌所需权限。

为了保护一个分支并确保只有经过验证的 pull 请求才能合并到其中，您可以在 GitHub 仓库设置中创建一个分支保护规则。如果您将 TeamCity 构建设置为必需的状态检查，那么在请求的更改的构建成功完成之前，GitHub 不允许合并拉取请求。

如果您的 VCS 根目录使用 App Token 连接到 GitHub，您可以利用 GitHub Checks API 在无需设置 Commit Status Publisher 功能的情况下，自动发布 Markdown 格式的构建状态。请参阅此文章获取更多信息： GitHub Checks Webhook 触发器。

GitLab

GitLab 凭证和 GitLab 项目必须按照以下步骤进行设置：

凭据必须属于具有开发者、维护者或项目所有者角色的用户。
GitLab 用户必须包含在允许推送列表中，以便能够更改受保护分支上的提交状态。
在 GitLab 项目的项目可见性设置中，请确保启用 CI/CD 选项（或者在旧版本的 GitLab 中启用 Pipelines 选项）。

GitLab API URL 字段接受 http[s]://<主机名>[:<端口>]/api/v4 格式的 URL。此字段为可选项：如果留空，TeamCity 将使用一个与 VCS 根设置中指定的获取 URL 相对应的值。

Bitbucket Cloud

要连接到 Bitbucket Cloud ，请确保 TeamCity 服务器 URL 是一个完全合格的域名（FQDN）：例如， http://myteamcity.domain.com:8111。短名称，如 http://myteamcity:8111 ，会被 Bitbucket API 拒绝。

Bitbucket Server

要保护一个分支，并确保只有经过验证的拉取请求才能合并到其中，您可以在您的 Bitbucket 仓库设置中指定必需的构建。要将 TeamCity 构建设置为必需构建，请打开 Bitbucket 中的添加所需的构建页面，并在添加构建字段中指定构建配置 ID 作为构建键。在这种情况下，Bitbucket 不会允许合并拉取请求，直到请求更改的构建成功完成。

JetBrains Space

从2023.11版本开始，通过预设的 Space connections设置的 TeamCity 构建配置不再需要配置 Commit Status Publisher 来发布构建状态。

使用 Space 连接设置项目后，TeamCity 将自动在 Space 的自动化部分以及提交和分支选项卡下发布与构建相关的评论。

也可以手动设置 Commit Status Publisher 功能。如果满足以下条件，您可以选择手动设置：

您希望设置自定义发布者名称和 / 或 Space 项目密钥；
TeamCity 无法自动发布构建状态（例如，如果您使用具有自定义配置的 JetBrains Space 的本地实例，可能会发生这种情况）。

要手动设置 Commit Status Publisher，您需要预定义的 Space connection。如果您没有合适的连接，并且您的项目是手动创建的或来自存储库 URL，请转到项目设置 | 连接并创建一个新连接。

然后，在构建配置的设置中：

打开构建功能并添加 Commit Status Publisher构建功能。
选择 JetBrains Space 发行商和已创建的连接。
指定将在 Space 中为此服务显示的名称。
保存设置。

Perforce Helix Swarm

如果在 Perforce 的 shelved files 中运行构建，TeamCity 可以将其状态以评论形式报告给 Perforce Helix Swarm 中的相应代码审查。

请参阅此帮助文章以获取更多信息：与 Perforce Helix Swarm 的集成。

Gerrit

Commit Status Publisher 支持 Gerrit 版本 2.6+。若要配置与早期 Gerrit 版本的集成，请联系我们的支持。

发布流水线运行状态

提交状态发布器是最常用的构建配置功能之一，因其配置简便并显著提升了整体可观测性。因此，我们已将此功能原生集成到流水线中：在仓库设置启用发布状态到存储库开关，TeamCity 会完成剩余操作。

使用 Commit Status Publisher 与 VCS 检出规则

如果构建的 VCS 根设置了检出规则，那么 Commit Status Publisher 将只考虑符合这些规则的提交。也就是说，如果构建开始前的最后一次提交不符合检出规则，它将不会被标记为构建状态；状态将显示在最后一次满足提交的旁边。

如果您需要在构建的最后一次提交旁边显示构建状态（例如，在拉取请求中），您可以调整检出规则，以便将此提交纳入 VCS 根的范围内。或者，如果这是一个经常出现的问题，您可以考虑按照以下方式重新安排您的构建链：

配置主构建的签出规则。
配置一个实用工具 composite build ，不包含构建步骤和检出规则，但包含 Commit Status Publisher 功能。
在复合构建中，为主构建配置一个快照依赖。

在这种链的范围内，Commit Status Publisher 将不受检出规则的约束，而构建状态将显示在最后一个提交旁边。

Kotlin DSL

在 Kotlin DSL中，在 buildType 实例的 功能 块中配置 jetbrains.buildServer.configs.kotlin.buildFeatures.CommitStatusPublisher 对象，以设置提交状态发布器。

buildType {
    // Other Build Type settings ...
    features {
        // Other Build Features ...
        commitStatusPublisher {
            vcsRootExtId = "${<VCS root object>.id}" // optional, publishes to all attached git VCS roots if omitted
            publisher = space {
                authType = connection {
                    connectionId = "<JetBrains Space connection id>"
                }
                displayName = "<Display name>" // optional, "TeamCity" by default
            }
        }
    }
}

  

更多信息请参见： CommitStatusPublisher｜Kotlin DSL 文档。

故障排查

TeamCity 写入事件与 Commit Status Publisher 构建功能相关到 teamcity-commit-status.log 文件。将 "debug-commit-status" 预设应用于此日志，以包含 DEBUG 级别的事件。

示例

以下示例演示了如何配置从 TeamCity 向 GitHub 发送包含在您的拉取请求中的构建状态更改。

使用 pull requests build feature 来配置 pull requests 分支。您也可以通过在您的 VCS Root 中配置分支规范来使分支可用，同时确保它包括拉取请求分支（也可以参见相关的博客文章）。
添加 Commit Status Publisher 构建功能：
- 使用默认的所有附加的 VCS 根选项为所有附加的 VCS 根中的提交发布状态。
- 选择 GitHub 作为发布者，并指定其连接详细信息及凭据，再测试连接：
保存您的设置。
将源代码的更改提交并在 GitHub 中创建拉取请求，然后在 TeamCity 中使用您的更改运行构建。 Commit Status Publisher 将会向您通报与您的拉取请求更改相关的构建状态：
- 它将向您展示检查是否为：
  - 进行中
  - 失败
  - 成功
- 将鼠标悬停在提交状态上会显示构建摘要
- 点击构建状态图标或详情链接，将在 TeamCity 中打开构建结果页面。此信息也可在您的拉取请求详情的提交选项卡中找到。
  与上一页面类似，点击构建状态图标会在 TeamCity UI 中打开构建结果页面：

2026年 8月 6日