> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gitar.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TeamCity

> Connect TeamCity so Gitar can read build logs and analyze failures

export const ThemeImage = ({src, alt, width}) => {
  let lightSrc, darkSrc;
  if (src.includes("-light.")) {
    lightSrc = src;
    darkSrc = src.replace("-light.", "-dark.");
  } else if (src.includes("-dark.")) {
    darkSrc = src;
    lightSrc = src.replace("-dark.", "-light.");
  } else {
    lightSrc = src;
    darkSrc = src;
  }
  const style = width ? {
    maxWidth: width,
    marginInline: "auto"
  } : undefined;
  return <span>
      <img className="block dark:hidden rounded-lg border" src={lightSrc} alt={alt} style={style} />
      <img className="hidden dark:block rounded-lg border" src={darkSrc} alt={alt} style={style} />
    </span>;
};

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](https://www.jetbrains.com/help/teamcity/commit-status-publisher.html) 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

<Steps>
  <Step title="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.

    <Note>
      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.
    </Note>
  </Step>

  <Step title="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.
  </Step>

  <Step title="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](/connecting-code/network-access).
  </Step>

  <Step title="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.

    <ThemeImage src="/assets/images/conn-teamcity-light.png" alt="TeamCity integration form with the access token and server URL" />

    <Note>
      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.
    </Note>
  </Step>
</Steps>

## 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](/features/ci-failure-analysis).

## Troubleshooting

<AccordionGroup>
  <Accordion title="Gitar does not comment on a failed build">
    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](https://www.jetbrains.com/help/teamcity/commit-status-publisher.html) 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.
  </Accordion>

  <Accordion title="The status link opens nothing, or opens an internal address">
    Set **Administration > Global Settings > Server URL** to the address Gitar can reach. TeamCity warns about a mismatch on its own dashboard when the URL you browse it at differs from the one configured.
  </Accordion>

  <Accordion title="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**. 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.
  </Accordion>

  <Accordion title="On-Premises on a private network">
    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](/connecting-code/network-access).
  </Accordion>
</AccordionGroup>

## 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

| Topic | TeamCity documentation |
| - | - |
| Access tokens | [Manage access tokens](https://www.jetbrains.com/help/teamcity/configuring-your-user-profile.html#Managing+Access+Tokens) |
| Roles and permissions | [Role and permission](https://www.jetbrains.com/help/teamcity/role-and-permission.html) |
| Reporting build status to a pull request | [Commit Status Publisher](https://www.jetbrains.com/help/teamcity/commit-status-publisher.html) |
| Server URL | [Global settings](https://www.jetbrains.com/help/teamcity/configuring-server-url.html) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.