Skip to main content
Gitar reads the log of every failing TeamCity build and analyzes it. Cloud and On-Premises both need one thing from you: a token that can read builds. TeamCity reports a build to the pull request as a status. That status links to the build, and Gitar fetches the log from the link. How you wire connections, VCS roots and triggers is yours.

​
Prerequisites

  • Confirm TeamCity reports build results to your pull requests, which needs the Commit Status Publisher build feature on the configurations you care about.
  • Get permission to create a user and grant it a role, if you want a dedicated one for Gitar.

​
Setup

1

Create an access token

In TeamCity, open the profile menu and go to My Settings & Tools > Access Tokens > Create access token. Copy the token. It starts with eyJ0eXAi, and TeamCity shows it once.A token carries the permissions of the user who made it, so make it as the user you want Gitar to read as.
Leave Expiration at Never, or note the date somewhere. An expired token stops log fetching, and the first sign of it is a red build Gitar says nothing about.
2

Give that user view access

Assign the Project Viewer role on the projects whose builds Gitar should read, or on All Projects for the whole server. Viewing a project carries viewing its build logs, which is the entire permission set Gitar needs.A dedicated user scoped to a subset of projects is the narrower grant, and it survives people leaving in a way a personal token does not.
3

Check the server URL TeamCity publishes

In Administration > Global Settings, confirm Server URL is the address Gitar can reach your server at. Every status link is built from it, so a server URL still set to localhost or an internal-only name publishes links nothing outside your network can open.On-Premises servers behind a firewall need network access arranged. See Network access.
4

Connect TeamCity in Gitar

  1. Go to your Gitar organization settings.
  2. Open Integrations.
  3. Find TeamCity and click Connect.
  4. Paste the access token into TeamCity Access Token.
  5. Set TeamCity Server URL to your server base URL, https://<tenant>.teamcity.com on Cloud or your own host on-premises.
  6. Click Connect to save. The card’s button changes to Configure once the token validates.
Gitar checks the host in each build link against the Server URL you enter, and ignores a status that points somewhere else. That is what keeps your token from being sent to a host you did not name.

​
What Gitar reads

Gitar reads the log of a failing build and passes it to CI failure analysis. It ignores a passing build, and writes nothing back to TeamCity. Results appear as a comment on the pull request. See CI failure analysis.

​
Troubleshooting

Check the pull request for a TeamCity status check.If there is no status, TeamCity is not reporting to your Git provider. Check the Commit Status Publisher build feature and the credential it uses, which needs permission to write statuses on the repository.If the status is there, check that TeamCity Server URL matches the host in the status link. Gitar drops the event on a mismatch.
The token resolves but its user cannot see the project. Grant Project Viewer on that project, or on All Projects. TeamCity evaluates permissions per request, so you do not need a new token.A revoked or expired token fails the same way. Tokens are listed under My Settings & Tools > Access Tokens for the user that made them.
Gitar cannot read a server reachable only over a VPN, PrivateLink, or an internal-only domain. Contact Gitar to arrange network access.See Network access.

​
Security notes

  • Gitar encrypts credentials and stores them in AWS Secrets Manager.
  • Prefer a dedicated user’s token over a personal one, so access survives people leaving.
  • Project Viewer is read-only. Gitar writes nothing to TeamCity.
  • Scope the role to the projects Gitar should read, if the whole server is more than you want to grant.
  • To revoke access, delete the token from My Settings & Tools > Access Tokens.

​
TeamCity references