# 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](/files/6el1pUEmKn1mBuzptgmM)

### 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="/files/sJkiwBaXcUkPacusTlEq" alt="" width="208"><figcaption></figcaption></figure>

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

<figure><img src="/files/dn42wDAmUVpWkW6u89Ci" alt="" width="260"><figcaption></figcaption></figure>

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

Name the token and pick your organization

<figure><img src="/files/hLlBka7mbs9Jukedw3NI" 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](/files/llOLARl5fENQZG8YlWIy)

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="/files/GWny5AyXfDlxlJhMvSOV" alt="" width="563"><figcaption></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.aviator.co/runbooks/how-to-guides/handling-ci-failure.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.