Manage Refreshable Access Tokens
In TeamCity, there are multiple entities whose functionality requires accessing VCS hosting providers: VCS roots, Commit Status Publishers, Pull Requests features, and so on. These entities typically offer multiple VCS authentication options:
Regular username/login credentials — being the most vulnerable, this authentication method is gradually deprecated by major VCS hosting providers.
Personal access tokens (PATs) — issued on the VCS provider's side and then copied into a TeamCity object. These tokens grant the same or fewer permissions as those of the issuing user.
Refreshable tokens — personal or non-personal tokens. To acquire this token, TeamCity communicates with a VCS provider using an existing OAuth (or OAuth-like) connection.
This topic explains how to issue, assign, and manage refreshable tokens.
Supported Connections
To issue a token, TeamCity communicates with a VCS hosting provider using a connection configured in project Connections settings. Currently, refreshable access tokens are supported for the following connections:
GitHub App (both regular and manifest-based connections)
Token Management
The VCS Auth Tokens page provides centralized access to all refreshable tokens issued for this project and its subprojects. To open this page:
Navigate to Administration | <Your Project> to access project settings. To view all tokens used on this server, open the Root project settings.
Click the VCS Auth Tokens settings tab.
This page allows you to find tokens by their names, related connections, and users who issued them. Without any filters applied, the page shows 10 most recently used tokens.
The Show inherited tokens checkbox allows you to view tokens issued in parent projects but available in the currently viewed project.
To issue a new token, click the Generate new token. In a dialog that pops up, specify the token name and a TeamCity connection. You can additionally limit the token scope to specific TeamCity projects and (for GitHub App tokens) VCS repositories.
Project Scope
Generated tokens are by default available for the currently edited project and all of its subprojects. That is, if you create a token from the Root project's VCS Auth Page, this token can be used by any project on the server by default. You can view projects for which a token was initially configured under the Project Scope.
Note that VCS Auth Tokens pages display only the tokens available for each project. If you create a new token for project A and restrict its scope to subprojects A.2 and A.3, TeamCity will notify you that the current project will not have access to this token and you will not be able to see this token after the dialog closes.
Repository Scope
GitHub App connections support granular per-repository token permissions. When creating a refreshable token using this connection, you need to specify which repositories this token can access. Enter repository names without user/organization names (myRepo instead of myUser/myRepo). Note that repositories must be hosted under the same account to which a corresponding GitHub App was installed.
For security reasons, you cannot issue a token with the global repository access permission.
How to Create and Assign Refreshable Tokens
You do not need to manually set up refreshable tokens for each object that requires access to VCS providers. For example, when you create a new project or configuration from an existing connection (by clicking a From <Connection_name> tile on the New Project/Configuration page), TeamCity will automatically generate a token and pass it to the related VCS root.
Similarly, when setting up build features like Commit Status Publisher, you may opt for employing default VCS root authorization method instead of issuing new tokens.
To assign a token manually, navigate to authentication settings of a build feature or a root. Here you can generate a new or use an existing token.
Generate new token
Click the Generate new button. Note that similarly to the VCS Auth Tokens page, this button is available only to project administrators.
Enter the token name and choose a TeamCity connection that should be used to communicate with the VCS provider. The project scope will be automatically limited to this project and its subprojects.
Click Save to exit the setup.
Choose an existing token
Click a pencil icon to enable the Token text box. Note that similarly to the VCS Auth Tokens page, this button is available only to project administrators.
Click the git token list link to open the VCS Auth Tokens page in a new tab.
On the VCS Auth Tokens page, locate a token you wish to use and click the Copy ID button.
Return back to the edited object and paste the token ID.
Click Save to exit the setup.