Commit Status Publisher

Common Settings

VCS root

The VCS root that carries out all TeamCity-to-VCS communication operations. This can be a separate VCS root, or the one that your build configuration/pipeline already uses to check out repository files.

Publisher

The type of your VCS. Other Commit Status Publisher settings vary depending on this setting.

Server URL

The URL of your VCS server. Use the default value for public services and enter a custom URL for on-premises solutions. For example, https://api.github.com for GitHub.com and http[s]://<host>[:<port>]/api/v3 for GitHub Enterprise.

Auth settings

These settings specify how Commit Status Publisher should authenticate to your VCS before it can post build statuses. You can click the Test connection button at the dialog's bottom to verify your current settings are valid.

For most of the VCS providers, you have the following options:

• Password — the classic username/password credentials pair. Note that most of the providers gradually deprecate this auth mode as least secure.

• Access token — authenticate using the personal access token that you should manually issue on the VCS side. For certain providers (for example, GitHub), you can click the magic wand button to let TeamCity automatically retrieve the access token using a pre-configured OAuth connection:

  

  Otherwise, issue with correct permissions manually. For example, for GitHub:

  • Classic GitHub tokens: public_repo and repo:status for public repositories; repo for private repositories. See also: Scopes for OAuth apps.

  • Fine-grained tokens: Add the Commit Statuses permission with the "Read and write" access type. This permission can only be added for tokens with the "All repositories" or "Only select repositories" access type. See also: Permissions required for fine-grained personal access tokens.

• Refreshable access tokens — use short-lived tokens acquired by TeamCity from a required VCS provider via existing OAuth/App connections (as opposed to static PAT tokens issued manually by users on a VCS hosting side). See the following article for more information on generating and using refreshable tokens: Manage Refreshable Access Tokens.

• Use VCS root credentials — TeamCity will try to extract credentials from the VCS root settings. This option is designed for VCS roots that use tokens (either static/personal or refreshable/OAuth) to pass authentication and obtain repositories using HTTP(S) fetch URLs. Choose other options if a related VCS root employs anonymous or standard username-password authentication or uses an SSH fetch URL.

Build name

The custom build name displayed in the status message. Allows you to include %parameter_name% parameter references. For example, overview section image shows statuses generated with the following custom build name:

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

This setting is available for all Git-based providers: Azure DevOps, Bitbucket Cloud, Bitbucket Server and Data Center, GitHub (the "Status check name" setting), GitLab ("External job name"), and JetBrains Space ("Display name").

Provider-specific Configuration

JetBrains Space

Starting with version 2023.11, TeamCity build configurations set up via predefined Space connections do not require a configured Commit Status Publisher to post build statuses.

Set up a project using Space connections and TeamCity will automatically post build-related comments under the Automation section of Space Commits and Branches tabs.

It is also possible to manually set up the Commit Status Publisher feature. You may opt a manual setup if:

• you want to set up a custom publisher name and/or Space project key;

• TeamCity is unable to publish build statuses automatically (for example, this may happen if you utilize an on-premises instance of JetBrains Space with a custom configuration).

To manually set up the Commit Status Publisher, you will need a predefined Space connection. If you do not have a suitable connection and your project was created manually or from the repository URL, go to Project settings | Connections and create a new one.

Then, in the build configuration's settings:

1. Open Build Features and add the Commit Status Publisher build feature.

2. Select the JetBrains Space publisher and the created connection.

3. Specify the name that will be displayed for this service in Space.

4. Save the settings.

Perforce Helix Swarm

If a build is run on changes in Perforce shelved files, TeamCity can report its statuses as comments to the respective code review in Perforce Helix Swarm.

See this help article for more information: Integration with Perforce Helix Swarm.

Publish Pipeline Run Statuses

Commit Status Publisher is one of the most frequently used build configuration features, as it is easy to configure and provides a clear benefit of improving the overall observability. For that reason, we have natively integrated this functionality in pipelines: enable the Publish status to repository toggle in the repository settings and TeamCity will do the rest.

Using Commit Status Publisher with VCS checkout rules

If a build's VCS root has checkout rules configured, Commit Status Publisher will consider only commits that conform to these rules. That is, if the last commit made before the build start does not satisfy the checkout rules, it will not be labeled with the build status; the status will be displayed next to the last satisfying commit instead.

If you need to display the build status next to the last commit of the build (for example, in a pull request), you can adjust the checkout rules so this commit is included into the VCS root's scope. Or, if this is a recurrent issue, consider rearranging your build chain as follows:

1. Configure the main build with checkout rules.

2. Configure an utility composite build without build steps and checkout rules but with the Commit Status Publisher feature.

3. In the composite build, configure a snapshot dependency on the main build.

In the scope of such a chain, Commit Status Publisher will not be bound by the checkout rules and the build status will be displayed next to the very last commit.

Kotlin DSL

In Kotlin DSL, configure the jetbrains.buildServer.configs.kotlin.buildFeatures.CommitStatusPublisher object inside the features block of a buildType instance to set up your commit status publisher.

See this link for more information: CommitStatusPublisher | Kotlin DSL docs.

Troubleshooting

TeamCity writes events related to the Commit Status Publisher build feature to the teamcity-commit-status.log file. Apply the "debug-commit-status" preset to include DEBUG-level events to this log.

Example

The example below demonstrates how to configure sending the status of builds with changes included in your pull request from TeamCity to GitHub.

1. Use pull requests build feature to configure pull requests branches. Alternatively you can make the branches available by configuring the branch specification in your VCS Root while ensuring that it includes pull requests branches (see also a related blog post).

2. Add the Commit Status Publisher build feature:

   • Use the default All attached VCS roots option to publish statuses for commits in all attached VCS roots

   • Select GitHub as the publisher and specify its connection details and credentials and test the connection:

     

3. Save your settings.

4. Commit changes to your source code and create a pull request in GitHub, then run a build with your changes in TeamCity. The Commit Status Publisher will inform you on the status of the build with your pull request changes:

   • It will show you whether the check is:

     • in progress

     • failed

     • successful

   • hovering over the commit status will display the build summary

   • clicking the build status icon or the Details link will open the build results page in TeamCity. This information is also available on the Commits tab of your pull request details.
     Similarly to the previous page, clicking the build status icon opens the build results page in the TeamCity UI: