TeamCity On-Premises 2023.11 Help

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:

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

    If you have a configured OAuth connection to GitHub, you can click the magic wand button to let TeamCity automatically retrieve the corresponding access token.

    Acquire access token for GitHub
  • GitHub App access token — if this project or any of the parent projects have a valid GitHub App connection, the Commit Status Publisher can use tokens issued through this connection. The Acquire new button allows you to instantly re-issue the access token. This option is available only if the VCS Root setting points to the specific VCS root configured via a GitHub App connection.

  • Use VCS root(s) 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.

  • 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

The Authentication Type option allows you to choose which authentication method the build feature should use to access GitLab repositories.

  • Personal access tokens or PATs are static authentication tokens that you can issue in your GitLab profile page.

  • Refreshable access tokens are short-lived tokens issued via configured GitLab OAuth 2.0 connections. Click the Acquire button next to a required connection to obtain an access token.

    Acquire access token for GitLab
  • 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.

The GitLab API URL field accepts URLs in the http[s]://<hostname>[:<port>]/api/v4 format. This field is optional: if left blank, TeamCity uses a value that corresponds to the fetch URL specified in VCS root settings.

Bitbucket Cloud

To be able to connect to Bitbucket Cloud, make sure the TeamCity server URL is a fully qualified domain name (FQDN): for example, http://myteamcity.domain.com:8111. Short names, such as http://myteamcity:8111, are rejected by the Bitbucket API.

For the Authentication Type, you have the following options:

  • 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.

  • Username/password — Specify a username and password for connection to Bitbucket Cloud. For Bitbucket Cloud team accounts, it is possible to use the team name as the username and the API key as the password. We recommend using an app password with the Pull Requests | Read scope.

  • Refreshable access token — Displays a list of configured Bitbucket Cloud OAuth connections. Click the Acquire button next to the connection that should be used to issue a short-lived OAuth token.

    PR Token for Bitbucket Cloud

Bitbucket Server

The following parameters are available for the Bitbucket Server/Data Center hosting type:

Parameter

Description

Bitbucket Server Base URL

Specifies the Bitbucket server base URL in the following format: http[s]://<hostname>:<port>.

If left empty, the URL will be extracted from the VCS root fetch URL.

Authentication Type

  • Username / Password — Specify a username and password for connection to Bitbucket Server/Data Center. You can submit an access token instead of the password. The token should have Read permissions for projects and repositories.

  • Use VCS root(s) 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.

  • Refreshable access token — Displays a list of configured Bitbucket Server/Data Center OAuth 2.0 connections. Click the Acquire button next to the connection that should be used to issue a short-lived OAuth token.

When you select the Refreshable access token authentication type, TeamCity displays a list of configured OAuth connections to Bitbucket Server / Data Center configured in the project and available to all project users. If a token is already configured, TeamCity displays the information about the user that obtained the token and the connection that provided the token.

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

To set up the Commit Status Publisher for Azure DevOps, specify your Azure server URL and choose a preferred authentication method.

  • Personal access tokens or PATs are static authentication tokens that you can issue in your Azure DevOps account settings. Your issued token should have the Code (status) and Code (read) scopes to allow Commit Status Publisher to post status updates. For VSTS connections, a token can be retrieved from connection settings automatically.

  • Refreshable access tokens are short-lived tokens issued via configured Azure OAuth 2.0 connections. Click the Acquire button next to a required connection to obtain an access token.

    Azure OAuth in CSP

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.

Publish Space build statuses

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.

Personal build in TeamCity

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

Gerrit

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

Using Commit Status Publisher

  1. Add the build feature to your build configuration.

  2. 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.

  3. Select your system as the publisher and specify its connection details and credentials.

  4. Test the connection

  5. 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.

  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:

      Testing connection to GitHub
  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 progress.png

      • failed Failed.png

      • successful Successful.png

    • 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:

    Build results

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.

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.

Last modified: 08 November 2023