Integrating TeamCity with VCS Hosting Services

If you have an organization account in GitHub.com, GitHub Enterprise, Bitbucket Cloud, GitLab.com, or GitLab CE/EE, you can connect TeamCity to these source code hosting services making it easier for the organization users to create new projects, Git or Mercurial VCS roots, GitHub or Bitbucket issue trackers, which are supported out of the box.

It is also possible to connect TeamCity to Azure DevOps Services making it really simple to set up projects which use VSTS repositories or issue tracker.

Configuring Connections

Connections are created on the project level, a configured connection is accessible in the current project and in all of its subprojects. If you use global VCS hosting services like GitHub or Bitbucket Cloud, it makes sense to configure a single connection for the Root project. Alternatively, your organization administrator can create a parent project and configure connection to GitHub there once, and the users will see a list of GitHub repositories URLs in the TeamCity web UI, which will make setting up subprojects a lot simpler for them.

Connections are configured on the Project Administration | Connections page.

You need to register your TeamCity application in your VCS hosting service using the information provided by TeamCity, enter the access details provided by the service in the TeamCity form, and log in to your VCS hosting service from TeamCity to authorize the TeamCity application in the VCS. See details below.

Connecting to GitHub

You will need a GitHub repository connection to create a project from GitHub URL, create a VCS root from URL, create a Git VCS root, create GitHub issue tracker, or enable GitHub authentication.

To configure a GitHub connection:

In Project Administration | Connections, click Add Connection.
Select GitHub.com or GitHub Enterprise as the connection type. The page that opens provides the parameters to be used when registering your TeamCity application in GitHub service.
Click the register application link. The GitHub page opens.
You need to register TeamCity as an OAuth application in GitHub.
The following steps are performed in your GitHub account:
- Sign in to your GitHub account. On the Register a new OAuth application page, specify the name and an optional description, the homepage URL and the callback URL as provided by TeamCity.
- Click Register application. The page is updated with Client ID and the client secret information for your TeamCity application.
If you use the GitHub authentication module and want to restrict access to TeamCity to users of specific GitHub organizations, you need to ensure that your OAuth app is allowed by all these organizations. By default, GitHub does not allow OAuth apps to access the organizations. You can either disable this restriction for all apps or approve only the TeamCity app in each of the required organizations. Please refer to the GitHub documentation for more details.
Continue configuring the connection in TeamCity. On the Add Connection page, specify:
- Application ID
- Secret
- Server URL (only for GitHub Enterprise)
Save the connection settings.
The connection is configured, and now a small GitHub icon becomes active in several places where a repository URL can be specified: create project from URL, create VCS root from URL, create Git VCS root, create GitHub issue tracker. Click the icon, log in to GitHub and authorize TeamCity. The authorized application will be granted full control of private repositories and the Write repository hooks permission.

Connecting to Bitbucket Cloud

You will need a Bitbucket Cloud connection to create a project from Bitbucket URL, create a VCS root from URL, create a Mercurial VCS root, create a Bitbucket issue tracker, or enable BitBucket Cloud authentication.

To configure a Bitbucket Cloud connection:

In Project Administration | Connections, click Add Connection.
Select Bitbucket as the connection type.
The page that opens provides the parameters to be used when registering an OAuth consumer on Bitbucket Cloud. Click the register application link.
You need to create an OAuth consumer on Bitbucket Cloud. The following steps are performed in your Bitbucket account:
1. Log into your Bitbucket account, click your avatar and select Bitbucket settings from the menu. The Account page opens.
2. Click OAuth from the menu bar. On the Add OAuth consumer page, specify the name and an optional description, the callback URL and the URL as provided by TeamCity.
3. Specify the set of permissions: TeamCity requires "read" access to your account and your repositories.
4. Save your settings.
5. On the page that opens, in the OAuth consumers section, click the name of your TeamCity application to display the key and the secret.
Continue configuring the connection in TeamCity: on the Add Connection page that is open, specify the key and secret.
Save the connection settings.
The connection is configured, and now a small Bitbucket icon becomes active in several places where a repository URL can be specified: create project from URL, create VCS root from URL, create Mercurial VCS root, create Bitbucket issue tracker. Click the icon, log in to Bitbucket and authorize TeamCity. TeamCity will be granted access to your public repositories. For private repositories you'll still have to provide Bitbucket credentials to be used for authentication by TeamCity, as Bitbucket Cloud doesn't provide non-expiring access tokens. See the related discussion.

Connecting to GitLab

You will need a GitLab connection to create a project from GitLab URL, create a VCS root from URL, or enable GitLab authentication.

To configure a GitLab connection in TeamCity:

In Project Administration | Connections, click Add Connection.
Select GitLab.com or GitLab CE/EE as the connection type.
TeamCity will display the Redirect URL required for registering an OAuth application in GitLab.
To register the application, follow this instruction. Insert the TeamCity Redirect URL as Redirect URI and select the api scope. Save your application, and copy the secret and application ID generated by GitLab.
Once ready, go back to configuring the connection in TeamCity and fill in the following fields:
- Application ID
- Secret
- Server URL (only for GitLab CE/EE)
Save the connection settings.
The connection is configured, and now a small GitLab icon becomes active in several places where a repository URL can be specified: create project from URL and create VCS root from URL. Click the icon, sign in to GitLab, and authorize TeamCity. TeamCity will be granted access to your repositories.

Connecting to Azure DevOps Services

You can configure a connection to your Azure DevOps Services (or Azure DevOps Server, formerly Team Foundation Server) to create a project from URL, create a VCS root from URL, create TFS VCS root, or create Team Foundation Work Items tracker.

To configure a connection to Azure DevOps Services, follow these steps:

In Project Administration | Connections, click Add Connection.
Select Azure DevOps Services as the connection type.
The page that opens provides the parameters to be used when connecting TeamCity to Azure DevOps Services.
Log in to your Azure DevOps Services account to create a personal access token with All scopes as described in the Microsoft documentation.
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
Save the connection settings.
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 of 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.

Creating Entities from URL in TeamCity

Now creating entities from a URL in TeamCity is extremely easy: on clicking the GitHub, Bitbucket, GitLab, or VSTS icon, the list of repositories available to the current user is displayed (note that only public Bitbucket repositories will be available via the configured connection):

You can select the URL and proceed with the configuration.

Last modified: 28 April 2021