Prerequisites
- TeamCity already reporting build results to your pull requests, i.e. the Commit Status Publisher build feature enabled on the configurations you care about
- 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 it immediately, it starts with
eyJ0eXAi and TeamCity does not show it again.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
- Navigate to your Gitar organization settings
- Go to the Integrations section
- Find the TeamCity integration and click “Connect”
- Paste the access token into TeamCity Access Token
- Set TeamCity Server URL to your server base URL,
https://<tenant>.teamcity.comon Cloud or your own host on-premises
Log fetching reads the server from the build link TeamCity posts, so the Server URL is what we check that link against. A status pointing at some other host is left alone, which is what keeps your token from being sent somewhere you did not name.
What Gitar reads
On a failing build, Gitar downloads that build’s log and hands it to CI failure analysis. A green build is left alone. Nothing is written back to TeamCity, Gitar comments on the pull request instead. See CI failure analysis for what happens with those logs.Troubleshooting
Gitar says nothing about a failed build
Gitar says nothing about a failed build
Open the pull request and look for a TeamCity status check. No status means TeamCity never told your Git provider the build ran, which is TeamCity-side configuration: Commit Status Publisher is where to look, and it needs a credential that can write statuses on the repository.If the status is there and Gitar still stayed quiet, check that TeamCity Server URL matches the host in the status link. A mismatch drops the event.
The status link opens nothing, or opens an internal address
The status link opens nothing, or opens an internal address
Administration -> Global Settings -> Server URL is what every link is built from. TeamCity warns about a mismatch on its own dashboard when the URL you browse it at differs from the one configured.
Log fetching fails on a build that exists
Log fetching fails on a build that exists
The token resolves but its user cannot see the project. Grant Project Viewer on that project, or on All Projects, and no new token is needed, permissions being evaluated per request.A revoked or expired token looks the same from the pull request. Tokens are listed under My Settings & Tools -> Access Tokens for the user that made them.
On-Premises on a private network
On-Premises on a private network
A server reachable only over a VPN, PrivateLink or an internal-only domain cannot be read from Gitar’s side. Reach out and we will wire up network access.See Network access for the general shape of this.
Security notes
- Tokens are encrypted and stored in AWS Secrets Manager
- Prefer a dedicated user’s token over a personal one, so access survives people leaving
- Project Viewer is read-only, and Gitar writes nothing to TeamCity. Grant nothing wider
- Scope the role to the projects Gitar should read if the whole server is more than you want to grant
- Revoke the token from TeamCity at any time to cut off access