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

# CI Failure Analysis

> Automatic analysis and fixes for CI failures on your pull requests

## Overview

Gitar monitors your CI pipelines and automatically analyzes failures on every PR. It identifies root causes, posts detailed breakdowns, and can push fixes.

## Which CI Platforms Need Connecting

Gitar reads CI logs so review and repair can follow the pipelines attached to the repository.

Gitar reads GitHub Actions, GitLab Pipelines, Bitbucket Pipelines, and Azure DevOps
Pipelines with no setup, using the credential from your code host connection.

Every other CI platform reports its builds to the pull request as a status check, and
Gitar needs its own credential to follow that link and fetch the log. Connect the ones in use:

| Platform | Guide |
| - | - |
| Jenkins | [Connect Jenkins](/connecting-ci/jenkins) |
| CircleCI | [Connect CircleCI](/connecting-ci/circleci) |
| Concourse (GitHub) | [Connect Concourse](/connecting-ci/concourse) |
| Buildkite | [Connect Buildkite](/connecting-ci/buildkite) |
| TeamCity | [Connect TeamCity](/connecting-ci/teamcity) |
| Harness | [Connect Harness](/connecting-ci/harness) |
| Bitrise | [Connect Bitrise](/connecting-ci/bitrise) |

## How It Works

When CI fails on a PR, Gitar automatically:

<Steps>
  <Step title="Analyze the failure">
    Gitar reads the CI logs, identifies the failing step, and determines the root cause of the failure.
  </Step>

  <Step title="Post an analysis comment">
    A detailed explanation of the failure is posted to the dashboard comment on your PR, including which files and lines are involved.
  </Step>

  <Step title="Suggest or apply a fix">
    Depending on your auto-apply setting, Gitar either waits for your approval or pushes a fix commit directly to the branch.
  </Step>
</Steps>

The analysis appears in the [Gitar dashboard comment](/gitar-dashboard) on your PR.

The analysis covers your full CI pipeline output, so Gitar can diagnose failures across multiple jobs and steps in a single run. Identical failures across multiple jobs are deduplicated so they only get analyzed once. CI events for outdated commits are ignored after you push new code.

| Failure Type | Examples |
| - | - |
| **Build errors** | Compilation failures, missing imports, type errors |
| **Test failures** | Broken assertions, missing setup, incorrect expected values |
| **Linting errors** | Code style violations, formatting issues, static analysis warnings |
| **Flaky tests** | Race conditions, timing issues, non-deterministic behavior |

## Applying Fixes

After Gitar posts its analysis, you have three options:

| Option | How |
| - | - |
| **Let Gitar auto-fix** | Enable auto-apply on the PR with `gitar auto-apply:on`. Gitar pushes a fix commit to your branch. |
| **Fix it yourself** | Use the root cause analysis as context and push your own fix. Gitar updates its analysis when new commits arrive. |
| **Request a targeted fix** | Comment `Gitar <specific instruction>` on the PR to tell Gitar exactly how you want the issue resolved. |

Auto-apply can be toggled at any time with `gitar auto-apply:on` / `gitar auto-apply:off`. See [Commands & Interactions](/commands) for all available commands.

## CI Retry for Unrelated Failures

Gitar can automatically retry CI jobs whose failures are not related to the changes in your PR, such as flaky tests, transient infrastructure hiccups, or failures caused by the target branch. When any failure in a pipeline is classified as unrelated to the PR, those jobs are rerun without any manual action, at most once per commit. Turn it on with **Retry unrelated CI failures** under **Settings -> Configuration -> Behavior**, independent from auto-apply.

Retry works on GitHub Actions, GitLab Pipelines, Bitbucket Pipelines, Azure DevOps Pipelines, and CircleCI. CircleCI reruns the whole workflow rather than a single job. Other connected CI platforms get failure analysis without retry.

On Azure DevOps Cloud and Server, the PAT needs **Build (Read & execute)** for retries. **Build (Read)** is enough for analysis. See the [Cloud](/connecting-code/azure-devops#build-read) or [Server](/connecting-code/azure-devops-server#build-read) setup guide.

## Recovery after a Gitar fix

When Gitar breaks previously passing CI, it can attempt a follow-up repair with auto-apply off. Recovery requires the latest failure to be related to the PR, with one or two consecutive Gitar commits after a commit whose CI passed.

This recovery is separate from retrying an unrelated flaky job. See [CI Retry for Unrelated Failures](#ci-retry-for-unrelated-failures) for that setting.

## Multi-Iteration Fixing

CI failures may not be resolved in a single pass. Gitar supports multi-iteration fixing:

1. Gitar pushes a fix for the original CI failure.
2. CI re-runs on the updated branch.
3. If CI fails again (whether from the same issue or one the fix introduced), Gitar re-analyzes the new failure.
4. Gitar attempts another fix, taking into account the full history of previous attempts.

Further automatic fixes depend on auto-apply or eligibility for recovery. Recovery stops after three consecutive Gitar commits. If CI still fails, inspect the analysis and request a targeted fix or push a correction.


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