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

# Concourse

> Connect Concourse so Gitar can read private 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 failed Concourse steps and explains the failure on the PR.

Concourse reports a build result to the PR as a status. That status links to the build, and Gitar fetches the logs from the configured server.

<Note>
  See [Platform support](/connecting-code/platform-support) for code-host availability.
</Note>

## Prerequisites

* Connect the repository to Gitar and enable [CI failure analysis](/features/ci-failure-analysis).
* Confirm Concourse reports build results to the PR. For VCS integration, see Concourse's [resources documentation](https://concourse-ci.org/docs/resources/) and [resource types directory](https://concourse-ci.org/resource-types-list/).
* Make the Concourse server reachable from Gitar over HTTPS, with a valid certificate. See [Network access](/connecting-code/network-access) for servers on private networks.
* Ask a Concourse administrator to create a dedicated local user and grant **viewer** access to the teams Gitar should read.
* Keep a completed private build with archived logs available for connection validation. A successful or failed build works.

## Setup

<Steps>
  <Step title="Prepare a viewer account">
    Create a dedicated [local user](https://concourse-ci.org/docs/auth-and-teams/configuring/local-user/) and assign the [viewer role](https://concourse-ci.org/docs/auth-and-teams/user-roles/) on each permitted team.

    Use that account's local username and password in Gitar. An SSO login or a copied `fly` session token cannot replace these credentials. With viewer access, Gitar reads private build logs without starting builds or changing pipelines.
  </Step>

  <Step title="Connect the server in Gitar">
    Open the Gitar organization's **Settings > Integrations**, find **Concourse**, and click **Connect**.

    | Field                       | Value                                                                                                             |
    | --------------------------- | ----------------------------------------------------------------------------------------------------------------- |
    | Connection name             | A label that distinguishes this server, such as `Build server`.                                                   |
    | Server URL                  | The HTTPS address Gitar can reach, such as `https://ci.example.com`. Include a base path if the server uses one.  |
    | Local username              | The dedicated Concourse user's login name.                                                                        |
    | Permitted teams             | Exact team names, separated by commas, such as `main, build-team`. The user must have viewer access to each team. |
    | Password                    | The local user's password.                                                                                        |
    | Completed private build URL | A build on this server in a permitted team, such as `https://ci.example.com/builds/42`.                           |

    <ThemeImage src="/assets/images/conn-concourse-light.png" alt="Concourse connection form with server URL, local user, permitted teams, password and a completed private build URL" />

    Click **Validate and save**. Gitar checks access to the build's logs before saving the connection.

    Each connection holds its own server address and password. Repeat this step for another server. To change a server already listed, use **Edit connection**.
  </Step>
</Steps>

## Manage credentials

Use **Edit connection** to save a rotated password, then validate against a completed private build. Leave **Password** blank to reuse the stored password when the server URL and username are unchanged. Changing either requires entering a password.

Use **Disconnect** to remove that server's configuration and saved credential from Gitar. To revoke the account itself, remove its team access or disable it in Concourse.

## What Gitar reads

Once connected, Gitar automatically reads failed-step logs and posts an analysis on the PR. It clears the failure analysis when CI recovers.

Gitar writes nothing back to Concourse. Starting or retrying a build through Gitar is not supported. See [CI failure analysis](/features/ci-failure-analysis).

## Troubleshooting

<AccordionGroup>
  <Accordion title="Validation cannot read the build">
    Confirm the username is a local Concourse user, the password is correct, and that user has viewer access to the build's team. Add the exact team name to **Permitted teams**.

    Use a completed build whose archived logs still exist. A running build can exceed the validation timeout. An SSO-only account cannot authenticate through this connection form.
  </Accordion>

  <Accordion title="The build URL does not match the server">
    Copy the build link from the same server saved in **Server URL**. Check the HTTPS hostname, port and base path. An alias or redirect to another address does not count as a match.
  </Accordion>

  <Accordion title="Gitar does not analyze a failed build">
    Check the PR for a failing status on its head commit with a Concourse build link. If no status appears, check the pipeline's VCS integration using Concourse's [resource types directory](https://concourse-ci.org/resource-types-list/).

    Confirm the matching Concourse connection is saved and that CI failure analysis is enabled for the repository. If logs have been pruned, run another build and test with its URL.
  </Accordion>

  <Accordion title="The server is not reachable">
    Confirm Gitar can reach the HTTPS endpoint and trust its certificate. A browser session on a company VPN does not prove Gitar has access. See [Network access](/connecting-code/network-access).
  </Accordion>
</AccordionGroup>