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

# Jenkins

> Connect Jenkins 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 Jenkins build and analyzes it.

Jenkins reports a build to the pull request as a status. That status links to the build, and Gitar fetches the log from the link.

Jenkins needs no plugin for this. The console log is a core endpoint.

## Prerequisites

* Confirm Jenkins reports build results to your pull requests. Multibranch pipelines using the [GitHub Branch Source](https://plugins.jenkins.io/github-branch-source/) plugin do this by default. Other jobs need the **Set GitHub commit status** publisher from the [GitHub](https://plugins.jenkins.io/github/) plugin.
* Confirm Gitar can reach your Jenkins URL. If your controller is not reachable from the internet, see [Network access](/connecting-code/network-access).
* Get permission to create a Jenkins user, if you want a dedicated one for Gitar.

## Setup

<Steps>
  <Step title="Create an API token">
    1. Sign in as the user you want Gitar to read as.
    2. Open the user menu and click **Configure**.
    3. Under **API Token**, click **Add new Token**, name it `Gitar`, and click **Generate**.
    4. Copy the token. Jenkins shows it once.

    <Note>
      Jenkins has no bearer-token mode. The token is the password half of HTTP Basic authentication and works only with its username, so Gitar asks for both.
    </Note>
  </Step>

  <Step title="Grant read access">
    Give the user **Overall/Read**, and **Job/Read** on the jobs Gitar should read. Read access to a job includes its console log, which is all Gitar needs.

    Granting **Job/Read** at the root covers every job. To narrow it, grant **Job/Read** on individual jobs or folders instead.
  </Step>

  <Step title="Check the Jenkins URL">
    Go to **Manage Jenkins > System** and confirm **Jenkins URL** is the address Gitar can reach, including any context path such as `https://example.com/jenkins`.

    Jenkins builds every link it publishes from this value. If it is set to `localhost` or an internal-only name, Gitar receives links it cannot open.
  </Step>

  <Step title="Enter the credentials in Gitar">
    1. Go to your Gitar organization settings.
    2. Open **Integrations**.
    3. Find **Jenkins** and click **Connect**.
    4. Enter the user's login in **Jenkins Username** and the token in **Jenkins API Token**.
    5. Set **Jenkins URL** to the value you confirmed in the previous step.

    <ThemeImage src="/assets/images/conn-jenkins-light.png" alt="Jenkins integration form with the username, API token and Jenkins URL" />

    <Note>
      Gitar checks the host in each build link against the Jenkins URL you enter, and ignores a status that points somewhere else.

      Jenkins has no hosted form, so this field is required. If you leave it blank, Gitar fetches no logs.
    </Note>
  </Step>
</Steps>

## Optional plugins

Gitar uses these when they are installed. Neither is required.

| Plugin | Effect |
| - | - |
| [Pipeline: Stage View](https://plugins.jenkins.io/pipeline-stage-view/) | Gitar reads the failing stage's log instead of the whole console. On a large build, this isolates the failure from everything around it. |
| [JUnit](https://plugins.jenkins.io/junit/) | Gitar reads failing test names and assertion messages alongside the log. |

Without either plugin, Gitar reads the whole console log.

## 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 Jenkins. 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 Jenkins status, usually `continuous-integration/jenkins/pr-head` or `pr-merge`.

    If there is no status, Jenkins is not reporting to your Git provider. For a multibranch pipeline, check the [GitHub Branch Source](https://plugins.jenkins.io/github-branch-source/) plugin and the credential it uses, which needs permission to write statuses on the repository.

    For other jobs, check the **Set GitHub commit status** publisher.

    If the status is there, check that **Jenkins URL** matches the host in the status link. Gitar drops the event on a mismatch.
  </Accordion>

  <Accordion title="The status link opens an internal address">
    Set **Manage Jenkins > System > Jenkins URL** to the address Gitar can reach. The change applies to new builds, not to statuses already published.
  </Accordion>

  <Accordion title="Log fetching fails on a build that exists">
    The credentials work but the user cannot see the job. Grant **Job/Read** on that job. Jenkins evaluates permissions per request, so you do not need a new token.

    A wrong username fails the same way as a wrong token, because HTTP Basic authentication reports both as one error. Check that the username is the user's login, not their display name.
  </Accordion>

  <Accordion title="A branch name contains a slash">
    No action needed. Jenkins encodes the slash in build URLs and Gitar reads the URL as published, so `feature/my-branch` behaves like any other branch.
  </Accordion>

  <Accordion title="Jenkins is on a private network">
    Gitar cannot read a controller 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.
* Overall/Read and Job/Read are read-only. Gitar writes nothing to Jenkins.
* Gitar checks the Jenkins URL against every build link before it uses a credential.
* To revoke access, delete the token from the user's **Configure** page.

## Jenkins references

| Topic | Jenkins documentation |
| - | - |
| API tokens | [Authenticating scripted clients](https://www.jenkins.io/doc/book/system-administration/authenticating-scripted-clients/) |
| Permissions | [Authorization](https://www.jenkins.io/doc/book/security/managing-security/#authorization) |
| Reporting build status | [GitHub Branch Source](https://plugins.jenkins.io/github-branch-source/) |
| Jenkins URL | [Jenkins URL](https://www.jenkins.io/doc/book/security/services/#jenkins-url) |


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