TeamCity On-Premises 2021.2 Help

Configuring Connections

TeamCity allows storing presets of connections to external services. You can reuse these presets in various places on the server: when creating projects, configuring notifications, integrating with issue trackers, and more. This article gives instructions on how to add each type of connection.

To add a connection, go the target project's settings, open the Connections page, and click Add Connection. Select the connection type, set its Display name to distinguish it from the others, and configure it as described below.

When created, a connection can be used in all the nested subprojects of the current project. If you add a connection in the Root project, it will become available on the whole server.

Azure DevOps

There are two types of Azure DevOps connections in TeamCity:

  • Azure DevOps OAuth 2.0 allows signing in to TeamCity via an Azure DevOps Services account.

  • Azure DevOps PAT allows creating TeamCity projects from Azure Git and TFVC repositories.

Azure DevOps OAuth 2.0 Connection

This type of connection supports only Azure DevOps Services. It uses the OAuth 2.0 protocol based on JWT tokens and requires creating a dedicated app in your Azure profile.

This connection can be used for enabling user authentication via Azure DevOps.

To configure an Azure DevOps OAuth 2.0 connection:

  1. In Project Administration | Connections, click Add Connection.

  2. Select Azure DevOps OAuth 2.0 as the connection type.

  3. TeamCity will display the Callback URL and scopes required for registering an OAuth application in Azure DevOps.
    Go to the Register Application page in Azure and create a new app using the provided parameters. When created, copy the app's ID and client secret.

  4. Go back to the connection form in TeamCity and enter the Azure DevOps Services URL, the new application ID, and client secret.

  5. Save the connection.

To activate the Azure DevOps Services authentication on your server, proceed to enabling the respective authentication module.

Azure DevOps PAT Connection

This type of connection uses personal access tokens. It allows creating a project from a Git or TFVC repository URL, creating a TFS VCS root, or integrating with the Team Foundation Work Items tracker.

To configure an Azure DevOps PAT connection:

  1. In Project Administration | Connections, click Add Connection.

  2. Select Azure DevOps PAT as the connection type.
    The page that opens provides the parameters to be used when connecting TeamCity to Azure DevOps Services.

  3. Log in to your Azure DevOps Services account to create a personal access token with All scopes as described in the Microsoft documentation.

  4. Continue configuring the connection in TeamCity: on the Add Connection page that is open, specify
    • the server URL in the https://{account}.visualstudio.com format or your Team Foundation Server web portal as https://{server}:8080/tfs/

    • your personal access token

  5. Save the connection settings.

  6. The connection is configured, and now a small Azure DevOps Services icon becomes active in several places where a repository URL can be specified: create project from URL, create VCS root from URL, create TFS VCS root, create Team Foundation Work Items tracker. Click the icon, log in to Azure DevOps Services and authorize TeamCity. TeamCity will be granted full access to all the resources that are available to you.
    When configuring Commit Status Publisher for Git repositories hosted in TFS/VSTS, the personal access token can be filled out automatically if a VSTS project connection is configured.

Bitbucket Cloud

A connection to Bitbucket Cloud can be used to:

The Bitbucket Cloud connection form provides multiple parameters. You need to use them for creating a new OAuth consumer in Bitbucket.

After the consumer is created:

  1. Copy its key and secret.

  2. Go back to the connection form in TeamCity.

  3. Paste the key and secret.

  4. Save the connection.

A Bitbucket icon will become active in several places where a repository URL can be specified. Click it to authorize TeamCity in your Bitbucket profile. TeamCity will be granted access to your public repositories. For private repositories, you will need to provide Bitbucket credentials to be used for authentication by TeamCity, as Bitbucket Cloud does not provide non-expiring access tokens. See the related discussion. If you configure multiple Bitbucket connections, the server URL will be displayed next to each icon, so it is easier to distinguish the server in use.

GitHub

There are two types of GitHub connections: GitHub Enterprise and GitHub.com. Choose it depending on your GitHub account type.

A connection to GitHub can be used to:

The GitHub connection form provides multiple parameters. You need to use them to create a new OAuth application in GitHub.

After the app is created:

  1. Copy its client ID and secret.

  2. Go back to the connection form in TeamCity.

  3. Paste the GitHub server URL (only for Enterprise) and the app ID and secret.

  4. Save the connection.

If you use a GitHub Enterprise server with HTTPS, you need to also upload its HTTPS certificate as described here.

A GitHub icon will become active in several places where a repository URL can be specified. Click it to authorize TeamCity in your GitHub profile. TeamCity will be granted full control of your private repositories and get the Write repository hooks permission. If you configure multiple GitHub integrations, the server URL will be displayed next to each icon, so it is easier to distinguish the server in use.

GitLab

There are two types of GitLab connections: GitLab CE/EE and GitLab.com. Choose it depending on your GitHub account type.

A connection to GitLab can be used to:

The GitLab connection form provides multiple parameters. You need to use them to create a new OAuth application in GitLab.

After the app is created:

  1. Copy its client ID and secret.

  2. Go back to the connection form in TeamCity.

  3. Paste the GitLab server URL (only for CE/EE) and the app ID and secret.

  4. Save the connection.

If you use a GitLab CE/EE server with HTTPS, you need to also upload its HTTPS certificate as described here.

A GitLab icon will become active in several places where a repository URL can be specified. Click it to authorize TeamCity in your GitLab profile. TeamCity will be granted access to your repositories. If you configure multiple GitLab connections, the server URL will be displayed next to each icon, so it is easier to distinguish the server in use.

Docker Registry

A connection to Docker Registry can be used to:

  • sign in to an authenticated Docker registry before running a build / sign out after the build;

  • clean up published images after the build.

See more information in the dedicated article.

Amazon ECR

An Amazon ECR (Elastic Container Registry) connection allows accessing private AWS registries. With its help, the Docker Support build feature can store Docker images produced by a build to a private registry.

Connection settings:

SettingDescription

AWS region

Select an AWS region where the target resources are located.

Credentials type

  • Access key: select to use preconfigured AWS account access keys. You can find them in the Identity and Access Management section of your AWS console.

  • Temporary credentials: get temporary access keys via AWS STS. Such credentials are short-term and can be revoked anytime. They do not belong to a specific user and can be provided on demand — to grant temporary access to specific resources.

IAM role ARN

(only for Temporary credentials)

Specify a role to be used for generating temporary credentials. You need to create this role in advance in your AWS console and assign it to all the permissions you need.

External ID

(only for Temporary credentials)

Specify an external ID. We strongly recommend that you always define it when using temporary credentials. This ensures that only TeamCity will be able to use the specified IAM role.

Default credential provider chain

Enable this option to automatically find access credentials according to the default chain.

This approach is recommended if you do not want to store the credentials anywhere in the TeamCity environment. By default, it will use the values of AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables.

Access key ID

Specify the access key ID.

See how to get it here.

Secret access key

Specify the secret access key.

See how to get it here.

Registry ID

Enter your account ID number.

Slack

This type of connection is used to enable notifications via Slack.

Before configuring a Slack connection, you need to create a Slack app with the following bot token scopes: channels:read, chat:write, im:read, im:write, users:read, team:read, groups:read. You can add these in Features | OAuth & Permissions | Scopes of your Slack app.

To ensure your TeamCity server can connect to Slack, specify all the possible endpoint addresses of the server as Redirect URLs in Features | OAuth & Permissions. In most cases, it would be enough to specify the Server URL set in Global Settings in TeamCity. However, if you use a proxy for your TeamCity server but access this server directly, the authentication in Slack might not work unless the server's IP address is also specified in Redirect URLs.

Now you can return to TeamCity, add a new Slack connection, and enter the following connection parameters:

  • client ID and secret from the app's Basic Information page;

  • a bot user token of your app.

Save the connection and proceed with adding a Notifier build feature.

JetBrains Space

This type of connection can be used for:

Before configuring this connection, you need to create a dedicated application in JetBrains Space:

  1. Go to Administration | Applications and click New application.

  2. Enter a convenient name and save the application.

  3. Open the app's Requested rights tab and enable the required permissions:
    • General access / authentication:
      • Members | View member profile
    • Required for Commit Status Publisher:
      • Git Repositories | Report external check status
  4. Open the Authentication tab and enable Client Credentials Flow. User authentication and creating projects/configurations from a repository require enabling Authorization Code Flow as well.

  5. In the Authentication tab, enter your TeamCity server's URL as the redirect URI.
    If you use the authorization code flow, you need to ensure that your TeamCity server can always connect to JetBrains Space. Specify all the other possible endpoint addresses of the server. In most cases, it would be enough to specify the Server URL set in Global Settings in TeamCity. However, if you use a proxy for your TeamCity server but access this server directly, the authentication might not work unless the server's IP address is also specified here.

  6. In the Authentication tab, copy the app's Client ID and Client secret.

Now you can return to TeamCity, add a new JetBrains Space connection, and enter the following connection parameters:

  • URL of the Space server

  • client ID and secret of your Space application

Save the connection and proceed with adding a Commit Status Publisher, enabling Space authentication, or creating a project/ build configuration.

NPM Registry

This type of connection allows accessing a private npm registry during a build.

Connection settings:

SettingDescription
Scope

Specify an npm user/organization's scope to associate with the connected registry. If you want to use multiple registries per project, you need to specify a scope for each of them.

Leave empty if you want to use only one registry in this project. It will be used by npm/ yarn commands by default.

Registry URL

Specify the npm registry URL in the following format: http(s)://hostname[:port]. For example, https://npm.pkg.jetbrains.space/mycompany/p/projectkey/mynpm. The HTTPS schema is used by default.

Access token

Specify a token, if it's needed for accessing the registry. Leave empty for anonymous access. Note that token-based authentication could differ depending on a registry type. See instructions for npm Enterprise, Space Packages, or GitHub Packages.

Save the connection and proceed with adding an NPM Registry Connection build feature.

Perforce Administrator Access

This type of connection allows processing task streams on your Perforce server. In the connection settings, enter the host and user credentials for accessing the Perforce server (the user must have the admin permission).

Last modified: 18 October 2021