TeamCity On-Premises 2023.05 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.

Create a new TeamCity connection

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.

If your TeamCity server is installed behind a proxy, it is important to ensure that this is reflected in the connection settings, if applicable. When configuring a callback URL for a connection, you need to specify all URLs by which the current server can be accessed.
After configuring the proxy, remember to also set the new address as the Server URL in Global Settings of TeamCity.

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 and creating TeamCity projects from Azure Git repositories.

  • 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 authenticating users via Azure DevOps as well as creating projects and build configurations.

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. Specify the application scope that must be the same as the scope of the created Azure DevOps OAuth App.

  6. 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 an Azure DevOps VCS root, or integrating with the Azure Board 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 Azure DevOps Server 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 Azure DevOps Server VCS root, create Azure Board 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 repositories. 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.

Bitbucket Server and Data Center

Integration with Bitbucket Server and Data Center currently allows you to:

To allow TeamCity to access Bitbucket data, you need to create an incoming application link in Bitbucket to grant TeamCity required permissions.

  1. Create a new connection and choose the "Bitbucket Server / Data Center" option.

  2. In a separate browser tab, go to the Bitbucket "Administration | Application Links" page.

  3. Create a new application link with the following parameters:

    • Application type: External application

    • Direction: Incoming

    • Redirect URL: <copy URL from the TeamCity new connection tab>

    • Application permissions: tick "Write" under "Repositories"

  4. Once the application link is ready, Bitbucket will generate the "Client ID" and "Client Secret" values. Copy these values and paste them into corresponding fields on the TeamCity new connection tab.

  5. Save the connection in TeamCity.

GitHub

TeamCity allows you to create connections to both regular GitHub.com instances and GitHub Enterprise.

A connection to GitHub can be used to:

Depending on your needs, you can create connections to GitHub that operate via GitHub Apps or GitHub OAuth Applications.

GitHub App

A GitHub App is an integration that allows third-party services such as TeamCity to connect to GitHub repositories without the necessity to keep a "service" user account. Compared to GitHub OAuth applications, GitHub Apps boast fine-grained permissions and grant you more control over which repositories the app can access. See this article for more information: Differences between GitHub Apps and OAuth Apps.

To create a TeamCity connection that utilizes a GitHub App:

  1. Go to Project Settings | Connections and click Add Connection.

  2. Choose GitHub App from the drop-down menu (regardless of whether you need to connect to regular GitHub or GitHub Enterprise).

  3. If you do not already have a GitHub App, follow TeamCity instructions to create and install a new App with required permissions. Note that GitHub will generate a private key in the process — save this .private-key.pem file in the secure location.

  4. Open the general settings of your GitHub App. Copy required values (App ID, client ID, cient secret) and paste them to the TeamCity dialog.

  5. If you have a GitHub App webhook configured, set its secret and copy the same value to the Webhook secret field. GitHub can use this webhook to notify the TeamCity server it should scan a repository for changes when they occur, instead of letting the server to constantly poll GitHub for changes. See also: Configuring VCS Post-Commit Hooks.

  6. Enter the Owner URL — the link to a personal account or organization where this GitHub App is installed.

  7. Upload the private key sent by GitHub.

  8. Click Save to save your new connection.

GitHub OAuth Application

OAuth Applications generate user access tokens and allow third-party services like TeamCity to perform actions on behalf of a user who authorized these services.

To create a TeamCity connection that utilizes a GitHub OAuth Application:

  1. Go to Project Settings | Connections and click Add Connection.

  2. Choose GitHub.com or GitHub Enterprise depending on which version you utilize.

  3. If you do not already have a GitHub OAuth Application, follow TeamCity instructions to create a new one.

  4. Copy the client ID and secret from OAuth Application's settings and paste them to the TeamCity dialog. For GitHub Enterprise you additionally need to paste the GitHub server URL.

  5. Click Save to save your new connection.

Once a connection is successfully configured, the 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.com for accounts hosted on the https://gitlab.com site, and GitLab CE/EE for accounts on a self-hosted GitLab Community Edition (CE) or Enterprise Edition (EE) server.

A connection to GitLab can be used to:

OAuth Applications generate user access tokens and allow third-party services like TeamCity to perform actions on behalf of a user who authorized these services.

To create a TeamCity connection that uses a GitLab OAuth Application:

  1. Choose the project where you would like to create a new connection, noting that the connection will only be available to the chosen project and its subprojects.

  2. Go to Project Settings | Connections and click Add Connection.

  3. Choose GitLab.com or GitLab CE/EE.

  4. If you do not already have a GitLab OAuth Application, follow the GitLab instructions to create an OAuth Application in one of the following scopes:

  5. When filling out the Add new application form in GitLab:

    1. Choose a Name for the application

    2. Copy the Redirect URL from the TeamCity dialog into the GitLab form

    3. Under Scopes, check api

    4. Click Save application

  6. Copy the Application ID and Secret from the GitLab Application settings and paste them into the TeamCity dialog.

  7. For a GitLab CE/EE connection, you must also enter the base URL of the GitLab CE/EE server (for example, https://gitlab.mydomain.com) into the Server URL field. Note that this field is not needed in the case of a GitLab.com connection, because the base URL is always https://gitlab.com.

  8. Click Save to save your new connection.

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.

Google

This type of connection supports Google Services. It uses the OAuth 2.0 protocol.

This connection is used for authentication in TeamCity with a Google account.

Before configuring a Google connection, you need to create a new Google project and register your app if you have not done it before.

To configure a Google connection in TeamCity:

  1. In the Administration area, select Root project | Connections, and click Add Connection.

  2. Select Google as the connection type.

  3. TeamCity will display the redirect URLs required for registering an OAuth client. Copy them.

  4. Go to the Credentials page in the Google project and create the OAuth client ID with the Web application type.

  5. Paste your Callback URLs to the Authorized redirect URIs section in Google OAuth client ID. When the OAuth client is created, copy the Client ID and Client Secret.

  6. Go back to the connection form in TeamCity, and enter the Client ID and Client secret.

  7. Save the connection.

Now you can enable the Google authentication module.

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 Web Services (AWS)

The Amazon Web Services (AWS) connection allows defining AWS credentials once and using them in builds via the AWS Credentials build feature. You can use different AWS credential types: access keys, IAM Role, and the Default credential provider chain.

To configure an AWS connection in TeamCity:

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

  2. Select Amazon Web Services (AWS) as the connection type.

  3. Provide a name to distinguish this connection from others.

  4. The Connection ID field is filled out automatically. You can modify it and provide your own unique ID.

  5. Select the AWS region where the target resources are located.

  6. From the Type drop-down, select one of the credential types:

    Access keys

    If you selected access keys as the credentials type, get the keys from the AWS console's Identity and Access Management section and provide them to TeamCity. See how to get these keys here.

    In the Access keys section in the TeamCity UI, do the following:

    1. Specify permanent Access keys:

      • Access key ID. Enter the access key ID.

      • Secret access Key. Enter the secret access key.

      It is recommended to change access keys regularly for security reasons. You will be able to do this after the connection is created via the Rotate key button.

      TeamCity will not revoke old keys immediately. After a new key is generated, TeamCity will preserve the old inactive key for 24 hours and then remove it. The lifetime of old keys can be changed via the following properties: teamcity.internal.cloud.aws.keyRotation.old.key.preserve.time.min or teamcity.internal.cloud.aws.keyRotation.old.key.preserve.time.days.

      To be able to successfully rotate access keys, TeamCity requires the iam:GetUser, iam:CreateAccessKey, and iam:DeleteAccessKey permissions.

    2. Configure temporary Session Settings:

      • Use session credentials. Check the box to use an endpoint that provides temporary access keys via AWS STS. Such credentials are short-term (the default session duration is 60 minutes). You can override the default session duration in the AWS Credentials build feature. These credentials do not belong to a specific user and can be provided on demand to grant temporary access to specific resources. We recommend using temporary credentials since they provide better security.

      • STS endpoint.

        • TeamCity generates this field automatically when changing the AWS region. The regional endpoint is recommended because it is faster and has lower latency. In addition, all calls to the regional endpoint are logged in AWS Cloud Trail as any regional service call.

        • Use the global endpoint if the selected regional endpoint is disabled on the Amazon account and you do not want to enable it.

        • Contact the TeamCity support team if you need to specify a custom endpoint for Amazon alternatives like MinIO.

    IAM Role

    Using IAM roles, you can delegate access to your AWS resources to users, applications, or services that usually don't have these permissions. These entities will assume this role to get such access.

    You can use the IAM Role as the credentials type only if you already have at least one AWS connection with access keys or default credential provider chain configured in this TeamCity project.

    1. Specify IAM Role:

      • AWS Connection. Select the AWS connection that will grant the specified IAM Role.

      • Role ARN. Specify the ARN of the role to assume by the connection you are creating.

    2. Configure Session settings:

      • Session tag. The session tag is required by Amazon. It is useful to locate sessions created by the TeamCity connection in AWS logs. TeamCity generates the tag automatically, but you can specify your own value.

      • STS endpoint.

        • TeamCity generates this field automatically when changing the AWS region. The regional endpoint is recommended because it is faster and has lower latency. In addition, all calls to the regional endpoint are logged in AWS Cloud Trail as any regional service call.

        • Use the global endpoint if the selected regional endpoint is disabled on the Amazon account and you do not want to enable it.

        • Contact the TeamCity support team if you need to specify a custom endpoint for Amazon alternatives like MinIO.

    After the connection is created, you can view and copy the automatically generated external connection ID. We strongly recommend that you always add it to the trust policy in AWS to prevent the confused deputy problem. This ensures that only authorized TeamCity AWS connections will be able to use the specified IAM Role.

    Default credential provider chain

    Select this type to provide access credentials according to the default chain. This approach provides an alternatives to storing credentials in plain text.

    To mitigate this risk, the Default credential provider chain credentials type is disabled by default. To enable it, set the internal property teamcity.internal.aws.connection.defaultCredentialsProviderEnabled=true. (The default value is false.) No server restart is required after the property is set. When this credentials type is used, TeamCity searches for credentials in the following order:

    1. Java System Properties: aws.accessKeyId and aws.secretAccessKey.

    2. Environment Variables: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

    3. Web Identity Token credentials from system properties or environment variables.

    4. Credential profiles file in the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI. The default location can be overridden via the AWS_SHARED_CREDENTIALS_FILE environment variable.

    5. Credentials delivered via the Amazon EC2 container service if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has access to it.

    6. Instance profile credentials delivered through the Amazon EC2 metadata service.

  7. Test and save the connection.

Now you can use the credentials provided by this connection in your builds. To do that, configure the AWS Credentials build feature.

Recommended Setup

Amazon key management guidelines recommend using IAM Roles instead of access keys and static IAM user credentials. Since IAM Roles issue short-lived credentials, this approach minimizes potential damage should your credentials get exposed (accidentally or as a result of a security breach).

TeamCity allows your project to access required AWS resources using connections that assume IAM Roles and do not rely on locally stored credentials.

  1. In AWS Management Console, go to the IAM dashboard and navigate to the Roles tab.

  2. Create a new IAM Role without any permissions. We will reference this role as "Role A".

  3. Configure your TeamCity server machine to access AWS using this role instead of locally stored credentials. Required steps may vary depending on the exact type of your machine.

  4. In TeamCity, create a new AWS connection of the Default Credentials Provider Chain type. Press Test Connection to ensure TeamCity uses your empty "Role A".

  5. Create a second IAM Role ("Role B") with permissions required to access AWS resources (for example, EC2 instances or S3 buckets).

  6. Modify the Trust relationships of this new Role B to allow Role A to assume it.

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "your-Role-A-ARN" }, "Action": "sts:AssumeRole" } ] }
  7. In a TeamCity project that needs access to AWS resources, create another AWS connection.

    • Type — "IAM Role".

    • AWS Connection — the connection created in step 4.

    • Role ARN — the ARN of "Role B".

  8. Click Test connection to ensure TeamCity can assume Role B.

    Running STS get-caller-identity... Caller Identity: Account ID: <your account ID> User ID: <user ID:session> ARN: <Role B ARN>
  9. Save your new connection and reopen it. You should now see the External ID value of the connection.

    External ID of an AWS Connection
  10. Go back to the Trust relationships of Role B and add the extra condition:

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "your-Role-A-ARN" }, "Condition": { "StringEquals": { "sts:ExternalId": "External-ID-copied-from-TeamCity" } }, "Action": "sts:AssumeRole" } ] }

As a result, you now have a following setup:

  • The primary Default credentials provider chain connection does not require locally stored credentials.

  • This shared primary connection has no permissions to access anything. To access AWS resources, it needs to assume other IAM roles.

  • Because of a condition configured in step 10, roles with actual access permissions can be assumed only by configured "IAM Role" TeamCity connections. TeamCity administrators cannot create more connections that utilize these roles.

    Incorrect External ID

    To create more connections that can access Amazon resources, your AWS administrator must add additional conditions to whitelist external IDs of these new connections.

Amazon ECR

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

Connection settings:

Setting

Description

Repository type

Choose to connect to a private or public registry.

AWS region

(Only for private registries) 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 send 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

Configured Slack connections are used by Notifier build features and Service Messages.

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. Go to the app's Authorization tab and click Configure requirements under the In-context Authorization section. Enter the name of the Space project you are about to access from TeamCity.

  4. Now, you need to set permissions that will be granted to the app in this project. Click Configure and enable the following permissions:

    • Required for authentication and Pull Requests:

      • Members | View member profile

    • Required for Commit Status Publisher:

      • Git Repositories | Report external check status

    • Required for Pull Requests:

      • Code Review | View code reviews

    You can approve project-level permissions right in this Authorization tab if you are the project's administrator. Global permissions like viewing a member profile require a server administrator's approval.

  5. Go back to the app's Overview and open the Authentication tab.

  6. Enable Client Credentials Flow.

  7. To be able to use authentication via Space in TeamCity or/and to create projects/configurations from Space repositories, enable Authorization Code Flow as well. Enter your TeamCity server's URL as the redirect URI.
    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.

  8. Copy the app's Client ID and Client secret.

Note: When you create a project in JetBrains Space, it does not automatically add you to this project as a member — this needs to be done manually. TeamCity will be able to see only those projects where you are listed as a member.

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 or Pull Requests feature, enabling Space authentication, or creating a project / build configuration / VCS root.

NPM Registry

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

Connection settings:

Setting

Description

Scope

Specify an npm user/organization's scope (with or without the @ character) 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 the 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: 06 November 2023