> For the complete documentation index, see [llms.txt](https://docs.nullify.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nullify.ai/connectors/circleci.md).

# CircleCI

## Overview

The CircleCI connector lets Nullify see your CI on the pull requests it opens. When Nullify pushes an autofix commit, your CircleCI pipeline runs against it like any other change, and Nullify learns the pass/fail result alongside the fix. Once connected, Nullify can:

* **See your CircleCI pipelines** on the pull requests it opens, including pass/fail status.
* **Hold an API token** for your CircleCI organization, stored encrypted, so Nullify can authenticate to the CircleCI API on your behalf.

The goal is the same autofix loop Nullify runs for other CI providers — fixes that are accountable to your actual pipeline, not just to Nullify's own checks.

{% hint style="info" %}
**Scope today.** Nullify already **detects** CircleCI builds from the GitHub commit status (`ci/circleci…`, or a `circleci.com` / `app.circleci.com` target URL) and stores your token. Automated **failed-build log fetching and autofix iteration** is live for Buildkite and Jenkins today; CircleCI log ingestion is rolling out. Connecting now provisions the credential so the loop activates automatically once enabled for your tenant — talk to your Nullify representative for current availability.
{% endhint %}

## How it works

Nullify never sits in the critical path of your pipeline and never changes how your builds run. It watches and reads:

1. **Nullify pushes an autofix commit** to a pull request.
2. **CircleCI runs your pipeline** against that commit, exactly as it would for any developer push.
3. **CircleCI reports the result to GitHub** as a commit status (this is CircleCI's standard GitHub integration), and Nullify detects it through its GitHub App.
4. **Nullify authenticates to the CircleCI API** with your stored token to read the failed pipeline's output and feed it back to the autofix agent.

The integration is **read-only on your CI**: Nullify reads build status and logs. It does not trigger, cancel, or modify your pipelines, and it does not write anything back to CircleCI.

## Prerequisites

Before you start, make sure you have:

* A **CircleCI organization** with at least one pipeline that runs on your pull requests.
* Your CircleCI organization **posting commit statuses to GitHub** (CircleCI's standard GitHub integration), so build results reach GitHub — and therefore Nullify.
* **GitHub already connected to Nullify.** CircleCI layers on top of the GitHub connection; it is not a standalone source-control integration.
* A **CircleCI personal API token** that can read the relevant projects. Nullify uses this single token to authenticate to the CircleCI API.

{% hint style="info" %}
**Use a dedicated service account for the API token, not a personal one.** Create a CircleCI user that exists only for Nullify, give it access to the relevant organization and projects, and mint the personal API token from that account (**User Settings → Personal API Tokens**). This keeps the integration alive when people change teams or leave, scopes Nullify's access to exactly what that user can see, and makes the token easy to audit and rotate.
{% endhint %}

## Configuration

Configure CircleCI through the Nullify dashboard (**Configure → Connectors → CircleCI**) or the admin API. The token you provide is stored encrypted in AWS SSM Parameter Store as a `SecureString` — Nullify never returns it back to you after it is saved.

### Connect via the admin API

Store the API token:

```http
POST /admin/integrations/circleci/token
Content-Type: application/json

{
  "apiToken": "<circleci-personal-api-token>"
}
```

`apiToken` is required.

Check whether a CircleCI integration is configured:

```http
GET /admin/integrations/circleci
```

```json
{ "configured": true }
```

Remove the integration (deletes the stored token):

```http
DELETE /admin/integrations/circleci
```

{% hint style="info" %}
Re-posting to `/admin/integrations/circleci/token` overwrites the stored token in place — that's also how you **rotate** it. There's no downtime: Nullify uses the new token the next time it reads a build.
{% endhint %}

## What data flows

| Direction              | Data                                                                                                                                    |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **GitHub → Nullify**   | Commit-status events for CircleCI builds on Nullify's pull requests (pass/fail and the build's target URL), via the Nullify GitHub App. |
| **CircleCI → Nullify** | Authenticated reads against the CircleCI API using your stored token (failed-build log ingestion rolling out — see the note above).     |
| **Nullify → CircleCI** | Nothing. Nullify only issues authenticated read requests; it never triggers, cancels, or configures pipelines.                          |

## Removing the integration

Delete the connector from **Configure → Connectors → CircleCI**, or call `DELETE /admin/integrations/circleci`. This removes your stored token from Nullify. Your CircleCI pipelines are untouched and keep running exactly as before — disconnecting only stops Nullify from reading build status and logs.