Commit Status Publisher

Commit Status Publisher is a build feature which allows TeamCity to automatically send build statuses of your commits to an external system. The feature is implemented as an open-source plugin bundled with TeamCity.

Supported systems:

GitHub (the build statuses for pull requests are supported as well)
GitLab
Azure DevOps (supported statuses: Pending, Succeeded, Failed, Error)
Bitbucket Server and Bitbucket Cloud
JetBrains Space
JetBrains Upsource
Gerrit Code Review tool 2.6+
Perforce Helix Swarm

Starting from version 2022.04, Commit Status Publisher updates the commit status in the version control system as soon as the build is added to the queue, providing you with the most up-to-date information. GitHub, GitLab, Space, Bitbucket Server and Bitbucket Cloud, Perforce Helix Swarm, and Azure DevOps are supported.

Provider-specific Configuration

GitHub

Commit Status Publisher supports the GitHub URL in the following format:

For GitHub.com: https://api.github.com
For GitHub Enterprise: http[s]://<host>[:<port>]/api/v3

For connection, select one of the available authentication types:

Access Token
Use a personal access token or obtain a token through an OAuth connection. The token must have the following scopes:
- for public repositories: public_repo and repo:status
- for private repositories: repo
Password
Provide the GitHub username and password.

Note that the password authentication will not work if connecting to a GitHub Enterprise repository or if the user's GitHub account is protected with a two-factor authentication. In these cases, use an access token instead.

GitLab

If you use a recent version of GitLab (<= 9.0), it is recommended to use the GitLab URL of the following format: http[s]://<hostname>[:<port>]/api/v4 as GitLab stops supporting the v3 API in GitLab 11. If you have /api/v3 in your current TeamCity configurations, they may stop working with GitLab 11+, so consider changing the server URL to api/v4.

For older versions of GitLab, use the GitLab URL of the format http[s]://<hostname>[:<port>]/api/v3.

Bitbucket Cloud

In the Commit Status Publisher settings, specify a username and app password (or token) for authentication. For Bitbucket Cloud team accounts, it is possible to use the team name as the username and the API key as the password.

Bitbucket Server

Commit Status Publisher supports the Bitbucket Server URL in the following format: http[s]://<hostname>:<port>. Apart from the URL, you need to specify a username and password (or token) for authentication.

To protect a branch and ensure that only verified pull requests are merged into it, you can specify required builds in your Bitbucket repository settings. To set a TeamCity build as a required build, open the Add required builds page in Bitbucket and specify a build configuration ID as a build key in the Add builds field. In this case, Bitbucket will not allow a pull request to be merged until the build on requested changes finishes successfully.

Azure DevOps

Personal access tokens can be used for authentication. If a VSTS connection is configured, the personal access token can be automatically filled from the project connection.

You can create a personal access token in your Azure DevOps account. Set the Code access scope to Code (status) in the repositories you are about to send statuses to from TeamCity.`

JetBrains Space

To establish integration with JetBrains Space, you need to create a predefined connection to it, as described here.

Then, in the build configuration's settings:

Open Build Features and add the Commit status publisher build feature.
Select the JetBrains Space publisher and the created connection.
Specify the name that will be displayed for this service in Space.
Save the settings.

Now, whenever you run a build in this configuration, TeamCity will report the build status to JetBrains Space.

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.

In the Commit Status Publisher settings, specify:

Your Helix Swarm server's URL.
Username and cross-host ticket for connection (use p4 login -a -p command to obtain one)
If you want TeamCity to create a test run on the Swarm server and update its status according to the build status in TeamCity. To be able to use this mode, make sure the provided credentials grant administrative access.

Note that Helix Swarm usually creates reviews on shelved changelists whose description contains a special keyword, depending on your setup (for example, #review). If you want TeamCity to trigger builds on Perforce shelved files automatically, you need to specify the same keyword in the Perforce Shelve Trigger settings as well.

Gerrit

Commit Status Publisher supports Gerrit versions 2.6+. For configuring integration with earlier Gerrit versions, contact our support.

Using Commit Status Publisher

Add the build feature to your build configuration.
Use the default All attached VCS roots option if you want Commit Status Publisher to attempt publishing statuses for commits in all attached VCS roots or select a single repository for publishing build statuses.
Select your system as the publisher and specify its connection details and credentials.
Test the connection
Save your settings.

Example: Configuring Pull Requests Status Publishing to GitHub

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

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).
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:
Save your settings.
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:

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:

Configure the main build with checkout rules.
Configure an utility composite build without build steps and checkout rules but with the Commit Status Publisher feature.
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.

Last modified: 17 August 2022