Skip to main content
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 plugin do this by default. Other jobs need the Set GitHub commit status publisher from the GitHub plugin.
  • Confirm Gitar can reach your Jenkins URL. If your controller is not reachable from the internet, see Network access.
  • Get permission to create a Jenkins user, if you want a dedicated one for Gitar.

​
Setup

1

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

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

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

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

​
Optional plugins

Gitar uses these when they are installed. Neither is required. 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.

​
Troubleshooting

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

​
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