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

# CircleCI

> Connect CircleCI for enhanced failure analysis and automatic fixes

export const ThemeImage = ({src, alt}) => {
  let lightSrc, darkSrc;
  if (src.includes("-light.")) {
    lightSrc = src;
    darkSrc = src.replace("-light.", "-dark.");
  } else if (src.includes("-dark.")) {
    darkSrc = src;
    lightSrc = src.replace("-dark.", "-light.");
  } else {
    lightSrc = src;
    darkSrc = src;
  }
  return <span>
      <img className="block dark:hidden rounded-lg border" src={lightSrc} alt={alt} />
      <img className="hidden dark:block rounded-lg border" src={darkSrc} alt={alt} />
    </span>;
};

Gitar automatically integrates with **GitHub Actions** and **GitLab Pipelines** -- no setup required. If you use CircleCI as an external CI platform, connect it here so Gitar can read build logs, analyze failures, and push fixes.

## Prerequisites

* Access to your CircleCI account
* A CircleCI Personal API Token
* Admin permissions in your organization (recommended for service accounts)

## Setup

<Steps>
  <Step title="Create a CircleCI Personal API Token">
    <Note>
      **Recommended: Use a Service Account.** Create a dedicated account like `circleci-integration@yourcompany.com` to prevent issues when team members leave and provide better audit trails.
    </Note>

    1. Log into your CircleCI account
    2. Go to [Personal API Tokens](https://app.circleci.com/settings/user/tokens)
    3. Click **"Create New Token"**
    4. Name it **"Gitar Integration"**
    5. Copy the token immediately (you won't be able to see it again)
  </Step>

  <Step title="Access Gitar Integrations">
    1. Navigate to your Gitar organization settings
    2. Go to the **Integrations** section
    3. Find the **CircleCI** integration
    4. Click **"Connect"** to begin the setup process
  </Step>

  <Step title="Configure and Connect">
    Enter your CircleCI Personal API Token. The token will be securely stored and encrypted.

    <ThemeImage src="/assets/images/conn-circleci-dark.png" alt="CircleCI integration form" />

    1. Fill in the required API token field
    2. Click **"Connect CircleCI"** to establish the connection
    3. If successful, the integration status will show as connected
    4. If the connection fails, verify your token is valid and has not expired
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection Failed">
    If your connection fails, verify:

    * CircleCI API token is correct and valid
    * Token has not expired
    * You have sufficient permissions in CircleCI
    * CircleCI service is accessible
  </Accordion>

  <Accordion title="Invalid Token Error">
    If you receive an "Invalid CircleCI API token" error:

    * Check that you've copied the token correctly
    * Verify the token hasn't expired
    * Ensure you're using a Personal API Token (not a Project API Token)
    * Try creating a new token if the issue persists
  </Accordion>

  <Accordion title="Missing Build Data">
    If Gitar isn't detecting your builds:

    * Ensure your repositories are connected to both your Git provider and CircleCI
    * Verify your CircleCI projects are properly configured
    * Check that status checks are enabled in your Git provider for CircleCI
  </Accordion>
</AccordionGroup>

## Security Notes

* API tokens are encrypted and securely stored using AWS Secrets Manager
* Tokens can be revoked at any time from your CircleCI account settings
* We recommend rotating tokens regularly for enhanced security
* Use service accounts for production environments to avoid disruption when team members leave
* Only grant the minimum required scopes for your use case