> ## 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 integrates with **GitHub Actions** and **GitLab Pipelines** with no setup. TeamCity (Cloud or On-Premises) needs one thing from you: a token that can read builds.

TeamCity reports a build to the pull request as a status, and that status links back to the build. Gitar reads the link, downloads the build log, and analyzes from there. How you wire connections, VCS roots and triggers is yours, we only need the status to show up with a link we can reach.

## Prerequisites

* TeamCity already reporting build results to your pull requests, i.e. the [Commit Status Publisher](https://www.jetbrains.com/help/teamcity/commit-status-publisher.html) 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

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

    <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. Navigate to your Gitar organization settings
    2. Go to the **Integrations** section
    3. Find the **TeamCity** integration 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

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

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

## 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](/features/ci-failure-analysis) for what happens with those logs.

## Troubleshooting

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

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

  <Accordion title="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](/connecting-code/network-access) for the general shape of this.
  </Accordion>
</AccordionGroup>

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

## TeamCity references

| Topic                                    | TeamCity docs                                                                                                             |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| 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)                           |
| The URL every status link is built from  | [Global settings](https://www.jetbrains.com/help/teamcity/configuring-server-url.html)                                    |