Configuring Connections

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.

Bitbucket Cloud

A connection to Bitbucket Cloud can be used to:

• Create a project from Bitbucket URL.

• Create a VCS root from URL.

• Create a Mercurial VCS root.

• Integrate with a Bitbucket Cloud issue tracker.

• Enable Bitbucket Cloud authentication.

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:

• create a project and build configuration from Bitbucket URL

• create a VCS root from URL

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

1. Navigate to Administration | <Your Project> to access project settings.

2. Switch to the Connections tab and click Add Connection. Note that connections can be used only in their parent projects and their subprojects. If you want a connection to be available globally, add it to the Root project.

3. Select "Bitbucket Server / Data Center" in the Connection Type drop-down menu.

4. Ensure the Enable unique callback URL setting is enabled to generate a unique ID added to your callback URL. This setting bolsters the security of your setup by mitigating the risk of mix-up attacks: attacks utilizing malicious authorization servers that impersonate real auth servers to trick a victim client into leaking an authorization code (token). Using the /oauth/bitbucketserver/rid:your_unique_id/accessToken.html URL format ensures an attacker cannot hand-craft an address acknowledged by TeamCity.

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

6. 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"

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

8. Click Test connection to verify TeamCity can access your resources, and save your new connection.

GitHub

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

A connection to GitHub can be used to:

• Create a project from GitHub URL.

• Create a VCS root from URL.

• Create a Git VCS root.

• Integrate with a GitHub issue tracker.

• Enable GitHub.com and GitHub Enterprise authentication.

• Provide access tokens for the Commit Status Publiser and Pull Requests build features.

• Connections via GitHub Apps can be used to configure webhooks that notify the TeamCity server about changes.

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.

In addition, configuration created via GitHub App connections can employ GitHub Checks Webhook triggers that replace the traditional combo of VCS trigger and Commit Status Publisher build feature.

If you do not already have a suitable GitHub App, you can allow TeamCity to register it and create a connection that employs this new app in one go. TeamCity uses manifests to register new GitHub Apps.

1. Navigate to Administration | <Your Project> to access project settings.

2. Switch to the Connections tab and click Add Connection. Note that connections can be used only in their parent projects and their subprojects. If you want a connection to be available globally, add it to the Root project.

3. Select "GitHub App" in the Connection Type drop-down menu. This connection type works with both regular GitHub and GitHub Enterprise accounts.

4. Select the Automatic creation mode to allow TeamCity to register a GitHub App from a manifest.

   

5. Specify the URL of your GitHub server (without "/username") and choose whether you want this app to send post-commit hooks and/or have access to your organization.

6. If the new GitHub App should provide access to organization repos, switch the Owner setting to Organization and enter the organization name in the corresponding field.

7. Follow instructions on your screen to log into your GitHub account, authorize TeamCity to register an app, and install it to your personal and/or organization account.

To manually create a new GitHub App and configure a TeamCity connection that uses this app:

1. Repeat steps 1 to 3 from the list above.

2. Switch the connection's creation mode to Manual.

3. Ensure the Enable unique callback URL setting is enabled to generate a unique ID added to your callback URL. This setting bolsters the security of your setup by mitigating the risk of mix-up attacks: attacks utilizing malicious authorization servers that impersonate real auth servers to trick a victim client into leaking an authorization code (token). Using the /oauth/githubapp/rid:your-unique-id/accessToken.html URL format ensures an attacker cannot hand-craft an address acknowledged by TeamCity.

4. In a separate browser tab, navigate to your GitHub account and follow instructions from the TeamCity connection description to create a new app. Note that GitHub will generate a private key in the process — save this .private-key.pem file in the secure location.

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

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

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

8. Upload the private key sent by GitHub.

9. Click Test connection to verify TeamCity can access your resources, and 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. Navigate to Administration | <Your Project> to access project settings.

2. Switch to the Connections tab and click Add Connection. Note that connections can be used only in their parent projects and their subprojects. If you want a connection to be available globally, add it to the Root project.

3. Select "GitHub.com or GitHub Enterprise" in the Connection Type drop-down menu.

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

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

6. Click Test connection to verify TeamCity can access your resources, and 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:

• Create a project from GitLab URL.

• Create a VCS root from URL.

• Integrate with a GitLab issue tracker.

• Enable GitLab.com authentication.

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. Navigate to Administration | <Your Project> to access project settings.

2. Switch to the Connections tab and click Add Connection. Note that connections can be used only in their parent projects and their subprojects. If you want a connection to be available globally, add it to the Root project.

3. Select "GitLab.com or GitLab CE/EE" in the Connection Type drop-down menu.

4. GitLab CE/EE connections only: Ensure the Enable unique callback URL setting is enabled to generate a unique ID added to your callback URL. This setting bolsters the security of your setup by mitigating the risk of mix-up attacks: attacks utilizing malicious authorization servers that impersonate real auth servers to trick a victim client into leaking an authorization code (token). Using the /oauth/gitlab/rid:your_unique_id/accessToken.html URL format ensures an attacker cannot hand-craft an address acknowledged by TeamCity.

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

   • User owned applications

   • Group owned applications

   • Instance-wide applications

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

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

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

9. Click Test connection to verify TeamCity can access your resources, and 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. Navigate to Administration | <Your Project> to access project settings.

2. Switch to the Connections tab and click Add Connection. Note that connections can be used only in their parent projects and their subprojects. If you want a connection to be available globally, add it to the Root project.

3. Select "Google" in the Connection Type drop-down menu.

4. Copy redirect URLs shown by TeamCity; these URLs are required to register an OAuth client.

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

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

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

8. Click Test connection to verify TeamCity can access your resources, and save your new 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. Navigate to Administration | <Your Project> to access project settings.

2. Switch to the Connections tab and click Add Connection. Note that connections can be used only in their parent projects and their subprojects. If you want a connection to be available globally, add it to the Root project.

3. Select "Amazon Web Services (AWS)" in the Connection Type drop-down menu.

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

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

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

7. 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. Note that if the target AWS connection belongs to a parent TeamCity project, this connection's Available for sub-projects setting must be enabled.

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

      # In ~/.aws/config [profile web-identity] role_arn=arn:aws:iam:123456789012:role/RoleNameToAssume web_identity_token_file=/path/to/a/token

   4. Credential profiles file in the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI.

      # In ~/.aws/credentials [default] aws_access_key_id = your_key aws_secret_access_key = your_secret

      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.

8. Tick the Available for sub-projects option if you want this connection to be available for all subprojects of the current project.

9. Tick the Available for build steps option to allow choosing this connection in the AWS Credentials build feature feature settings.

10. Click Test connection to verify TeamCity can access your resources, and save your new connection.

A configured AWS connection can supply credentials to the AWS Credentials build feature, artifact S3 storages, EC2 cloud profiles and other AWS connections that use IAM Roles.

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:

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:

• Publishing build statuses in JetBrains Space with the help of Commit Status Publisher.

• Authenticating in TeamCity with a JetBrains Space account.

• Creating projects, build configurations, and VCS roots from a JetBrains Space repository.

• Starting builds on merge requests created in a JetBrains Space repository.

There are two ways to configure Space connections:

• Automatically — TeamCity configures read-only Space applications with all required permissions and installs them to your Space instance.

• Manually — requires you to manually create and install Space applications, then set up connection settings in TeamCity.

Automatic Connections

To configure a TeamCity project that builds and deploys a repository stored in JetBrains Space, you need two separate connections:

• Organization connection — an entry point that stores common connection settings, which allow TeamCity to access your Space instance.

• Project connection — allows TeamCity to access one specific project and its repositories.

You only need a single organization connection configured in a parent TeamCity project. However, to access separate Space projects, you will require separate project connections.

To configure an organization connection:

1. Navigate to Administration | <Your Project> to access project settings.

2. Switch to the Connections tab and click Add Connection. Note that connections can be used only in their parent projects and their subprojects. If you want a connection to be available globally, add it to the Root project.

3. Select "JetBrains Space" in the Connection Type drop-down menu.

4. Choose Automatic: Organization Connection under Creation mode.

5. Enter the name for your new connection and click Create Space Application.

6. TeamCity will open a separate browser window that allows you to choose the required Space instance:

   

   • Space Cloud — click Install next to the required Space Cloud instance, or click Try another email if you are currently logged in using a different user account.

   • Space On-Premises — enter Space organization URL and click Install.

7. Enter the Space application's name and optional description, and click Install.

   

8. Click Approve all and go back to TeamCity to grant the newly installed Space application required permissions.

With the organization connection configured and installed, TeamCity has permissions to install other applications and scan for the list of projects. Add a new build configuration or create a new VCS root choosing organization connection as a source to view this list (you will need to authorize TeamCity at the first attempt):

Note that all projects initially have grayed-out Space icons. This means TeamCity cannot access repositories in these projects yet. To grant TeamCity required permissions:

1. Click a required project.

2. Click Proceed. TeamCity will create and install a new pre-configured application with all permissions required to access this specific project.

3. Follow instructions on the screen to navigate to Space administration dashboard and approve these permission requests.

You should now see all repositories added to this project. Space projects with installed applications that grant TeamCity access to their repositories show colored Space icons.

You can add more project connections to allow TeamCity to access additional Space projects within the same organization. To do this, navigate to Administration | <Your Project> | Connections and create new Space connections with the Automatic: Project Connection creation type. This option becomes available once you add an organization connection to this project (or its parent).

Individual Space project connections can also be employed by Commit Status Publisher and Pull Requests build features to interact with project repositories. Space organization connections in turn allow your users to log in TeamCity using their Space credentials.

Space applications configured by project-level automatic connections issue access tokens that VCS roots and build features utilize to access project repositories. These access tokens are non-personal, which means if a user who initially set up TeamCity projects and issued tokens leaves your organization, these projects remain functional and do not require an update. See this article for more information on refreshable tokens: Manage Refreshable Access Tokens.

Kubernetes

Kubernetes connections allow TeamCity to access your Kubernetes resources. These connections can be used to offload building tasks to K8s clusters.

1. Navigate to Administration | <Your Project> to access project settings.

2. Switch to the Connections tab and click Add Connection. Note that connections can be used only in their parent projects and their subprojects. If you want a connection to be available globally, add it to the Root project.

3. Select "Kubernetes Connection" in the Connection Type drop-down menu.

4. Specify the URL of the Kubernetes API server.

5. Enter the content of the CA certificate for your cluster.

6. Specify a required Kubernetes namespace. Leave empty to use the default namespace.

7. Select the required authentication strategy. Depending on the selected strategy, the set of additional options will vary. Refer to the Kubernetes documentation for details on available options.

8. Click Test connection to verify TeamCity can access your resources, and save your new connection.

NPM Registry

This type of connection allows the Node.js runner to access a private npm registry during a build. Since a project can have multiple NPM registry connections, you also need to configure the related build feature to choose a connection that Node.js build steps should utilize.

Connection settings:

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