How-To's Tips & Tricks

TeamCity to Access Private GitHub Repositories Securely


One of the great features TeamCity has is its integration with GitHub. Authentication from TeamCity to GitHub should be configured for the integration to work. We consider TeamCity secure enough; however, stealing authentication data is a threat we all live with and the consequences of it should be clearly understood.

In this blog post we’ll go over the existing ways of configuring authentication in TeamCity VCS roots pointing to private GitHub repositories, discussing the advantages and disadvantages of each of them. We hope that TeamCity Server administrators and Project administrators will find this information useful when deciding on the approach to authentication from TeamCity to GitHub.

Username and Password Authentication

It is often the case when access to a repository from TeamCity is configured via a user’s GitHub username/password. All server administrators and administrators of the projects where the root is configured have access to this information.

If this data is stolen, it gives the intruder full access and the possibility to maliciously modify your GitHub repositories, including your GitHub profile and all your settings.

We do not recommend it as it seems to be the least secure approach.

Username and Generated OAuth Token

Not long ago TeamCity started to support OAuth for GitHub. In this case you use the username and a generated OAuth token.

If someone gains access to them, then all your repositories in all organizations where you have read rights will be at this user’s disposal as TeamCity uses the ‘repo’ token scope.
However, this authentication option gives access to repositories only and not your GitHub profile and settings; besides, it is easy to revoke this token. Besides, repositories cannot not be deleted, and although force-push may still be performed, using the protected branches feature of GitHub can help in this case. All in all, this way can be considered an improvement in comparison with the previous approach.


As an administrator, you can create an SSH key for your TeamCity server, with the public part of the SSH key uploaded to GitHub and the private part uploaded to the TeamCity server.

The advantages of this approach are the same as those of the one above.
As to the risks, it can be highly dangerous if you use this key in different servers and applications. This can be mitigated using the special SSH key added to the GitHub profile and TeamCity, which will be used for this integration exclusively.

‘Deploy Key’ GitHub Feature

For every GitHub repository that Teamcity has access to it is possible to generate an SSH key with the private part on the TeamCity and the public part added to the deploy keys of your repository using the repository settings page. GitHub administrator rights for this repository are required. The key can have either read-only or read-write permissions for the repository.

This seems to be the most secure approach, because an individual key can be added to each repository, which would make access revocation extremely easy in case of data loss.

Creating a key for every repository might be a nuisance for Windows users, this seems to be the main disadvantage (not affecting Linux or macOS users though).


From the approaches outlined above, using OAuth token authentication and Deploy keys are considered secure enough by the majority of people, with Deploy keys being more secure and therefore recommended by us. In the end, adopting this or that way is up to you.

image description