# Handling CI failure

This guide gives an overview of how Runbooks agents auto-fix CI failures. Runbooks agents currently can only fix failure in pull requests generated by Runbooks.

### Detecting CI failure

Runbooks framework automatically track any CI failures on the pull requests that are generated by Runbooks. Once the in-flight and queued steps are completed, Runbooks agents start monitoring the CI status checks of the commit SHA.

A few things to note:

* If there are multiple PRs generated by Runbooks, all PRs are monitored for CI status check.
* Runbooks only tracks the latest head commit SHA for each PR.
* If latest head commit SHA is added manually (not be Runbooks), CI is not monitored.
* If a new commit gets added in middle of the CI validation workflow, the CI rework workflow is terminated.
* Runbooks will monitor all CI checks that are reported in GitHub and will work through only the first failed status check among one of the supported CI (see below).

### Rework config

By default, Runbooks agents will attempt fixing the CI 2 times. This property can be updated via Runbooks Config > Pull Requests > **CI Failure Auto-Rework.**

For every attempt, Runbooks agents will also publish a summary as a GitHub comment.

![Screenshot 2025-12-11 at 11.49.54 AM.png](https://273246003-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOAPqUQVbLbsfI5YESl32%2Fuploads%2F8rGA7SPfbip3MgY0fz2H%2FScreenshot%202025-12-11%20at%2011.49.54%E2%80%AFAM.png?alt=media\&token=789aee26-b09a-4186-bf32-553dbe63d8ec)

### Supported CI

To understand the CI failure reason, Runbooks agents analyze the CI logs

#### GitHub workfows

GitHub workflows are natively supported and no additional permissions are required.

#### Buildkite

To access Buildkite logs, you must provide the Buildkite API token through the [Workspace integrations page](https://app.aviator.co/settings/workspace/integrations):

**Step 1**: Go to “Personal Settings” from the top-right corner

<figure><img src="https://273246003-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOAPqUQVbLbsfI5YESl32%2Fuploads%2FWsEUFdNS44BaQMhw03xI%2Fimage%20(3).png?alt=media&#x26;token=2a468eca-d663-476d-ad71-048f4a4f8257" alt="" width="208"><figcaption></figcaption></figure>

**Step 2**: Click “API Access Tokens”

<figure><img src="https://273246003-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOAPqUQVbLbsfI5YESl32%2Fuploads%2FWXuot9Ia6jx9KNVwCZXM%2Fimage%20(4).png?alt=media&#x26;token=390a5e41-427a-43d0-b520-95f1b80d7776" alt="" width="260"><figcaption></figcaption></figure>

**Step 3**: Click “New API Access Token”

Name the token and pick your organization

<figure><img src="https://273246003-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOAPqUQVbLbsfI5YESl32%2Fuploads%2FpzfI99xxyyJJv4UDAeKg%2Fimage%20(5).png?alt=media&#x26;token=63c42364-827d-48e5-aab8-9a195f3780a1" alt=""><figcaption></figcaption></figure>

Choose “**Read Artifacts**”, “**Read Builds**”, “**Read Build logs**”, and “**Read Pipelines”**.

![Screenshot 2025-12-11 at 11.44.17 AM.png](https://273246003-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOAPqUQVbLbsfI5YESl32%2Fuploads%2FsFLjkbU6sCwMXPZmIyiI%2FScreenshot%202025-12-11%20at%2011.44.17%E2%80%AFAM.png?alt=media\&token=1b9cb413-0599-4680-98c8-2cb77bfb8077)

Click “Create New API Access Token”

**Step 4**: Copy the created access token, and go to <https://app.aviator.co/settings/workspace/integrations>, paste the created access token to the Buildkite integration.

<figure><img src="https://273246003-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOAPqUQVbLbsfI5YESl32%2Fuploads%2FfIUO13XofVDjzAzdKhO1%2FUntitled%20(5).png?alt=media&#x26;token=31e83d88-e18b-4008-889a-3e2908260363" alt="" width="563"><figcaption></figcaption></figure>