GitHub App VCS Auth Token: Add repositories without editing every VCS root

Background/Situation

A GitHub App connection issues refreshable tokens on the VCS Auth Tokens page of the project settings. Each token is restricted to the repositories listed when the token is generated. A VCS root refers to the token by its ID. Applies to TeamCity On-Premises 2026.2.2.

Question

How to add repositories to an existing GitHub App token without generating a new token and updating every VCS root?

Answer

The repository list of an existing GitHub App token cannot be edited. TeamCity sets the list when it issues the token, and the VCS Auth Tokens page only generates, shows, and deletes tokens. This is by design. For security reasons, a GitHub App token can reach only the repositories in its list.

Existing VCS roots need no change when new repositories are added. Each VCS root stores its own token ID, and a token only has to cover the repositories of the VCS roots that use it.

New VCS roots

New VCS roots can use the existing token. According to the Repository Scope section of the TeamCity documentation, pasting the token ID into a new Git VCS root expands the token's repository scope automatically. The scope also expands when subprojects and build configurations are created with the wizards, copied, or moved. Test connection on the VCS root page shows whether the token reaches the new repository.

Existing VCS roots on a new token

The TeamCity REST API can switch existing VCS roots to a new token, for example one generated with the complete repository list:

1. On the VCS Auth Tokens page, copy the IDs of the old token and the new token with Copy ID.
2. List the VCS roots that use the old token:

   curl -H "Authorization: Bearer <TeamCity access token>" --get "https://<TeamCity server>/app/rest/vcs-roots" --data-urlencode "locator=property:(name:tokenId,value:(<old token ID>))"
   

3. For each VCS root ID from step 2, set the new token:

   curl -H "Authorization: Bearer <TeamCity access token>" -X PUT -H "Content-Type: text/plain" --data "<new token ID>" "https://<TeamCity server>/app/rest/vcs-roots/id:<VCS root ID>/properties/tokenId"
   

For a project that stores its settings in VCS as Kotlin DSL, change the tokenId parameter of its VCS roots in the DSL code instead.

A new token can also be generated with the REST API, as described in Creating a GitHub App access token with REST API.

The feature request TW-100575 asks for GitHub App tokens that cover every repository the GitHub App installation can access.