# Circleci

SureCloud connects to CircleCI to retrieve pipeline configuration, workflow run history, and project security settings. This allows SureCloud to verify that CI/CD pipelines include required security steps — such as dependency scanning, SAST, and image scanning — and that code changes are subject to automated testing and approval gates before deployment.

## Authentication and setup

CircleCI authenticates API requests using a personal API token. SureCloud uses a token associated with a CircleCI user with read access to the relevant projects and organisations.

{% stepper %}
{% step %}
**Create a dedicated CircleCI user (recommended)**

Create a machine user account in your version control system (e.g. a GitHub or GitLab service account) and add it to your CircleCI organisation with read-only access. Using a dedicated machine user ensures the token remains valid if individual team members leave.
{% endstep %}

{% step %}
**Generate a personal API token in CircleCI**

Log in to [circleci.com](https://circleci.com/) as the machine user (or a suitable admin account). Navigate to **User Settings → Personal API Tokens** and click **Create New Token**. Name it `SureCloud CCM`. Copy the token.
{% endstep %}

{% step %}
**Enter the token in SureCloud**

Navigate to **SureCloud → Integrations → CircleCI → Connect**. Paste the API token and click **Save**. Click **Test Connection** to confirm access.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Store the API token securely. SureCloud encrypts it at rest, but treat it as a sensitive credential. Rotate it every 90 days in **CircleCI → User Settings → Personal API Tokens** and update it in **SureCloud → Integrations → CircleCI → Edit Connection**.
{% endhint %}

## Endpoints

| API Call                                      | Use Case                                                                                  |
| --------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `GET /api/v2/me`                              | Verify token and retrieve authenticated user details                                      |
| `GET /api/v2/me/collaborations`               | Enumerate organisations the token account belongs to                                      |
| `GET /api/v2/pipeline?org-slug={slug}`        | Retrieve pipeline run history for an organisation                                         |
| `GET /api/v2/pipeline/{pipeline-id}/workflow` | Retrieve workflows associated with a pipeline run                                         |
| `GET /api/v2/workflow/{workflow-id}/job`      | Retrieve individual job details within a workflow to confirm security steps executed      |
| `GET /api/v2/project/{project-slug}/pipeline` | Retrieve pipeline history for a specific project                                          |
| `GET /api/v2/context`                         | Enumerate CircleCI contexts (environment variable groups) for secrets management evidence |

## Pagination

`GET /api/v2/pipeline` and `GET /api/v2/project/{project-slug}/pipeline` use page token pagination. SureCloud uses the `next_page_token` value from each response as the `page-token` parameter in the next request, continuing until no `next_page_token` is returned.

```json
GET /api/v2/project/{project-slug}/pipeline?page-token=<value_from_previous_response>
```

`GET /api/v2/workflow/{workflow-id}/job` and `GET /api/v2/context` use the same pattern.

## Required permissions

SureCloud requires a CircleCI personal API token for an account that is a member of the target CircleCI organisation. The token needs access to:

* Pipeline and workflow history (read)
* Job details (read)
* Context list (read)

No trigger, cancel, or admin permissions are required. CircleCI personal API tokens are read-capable by default for all resources visible to the user.

## Polling frequency

| Data Type                         | Interval       |
| --------------------------------- | -------------- |
| Pipeline and workflow run history | Every 6 hours  |
| Job execution details             | Every 6 hours  |
| Context inventory                 | Every 24 hours |

## Troubleshooting

<details>

<summary>Connection test returns 401 Unauthorized</summary>

The API token is invalid or has been deleted. Navigate to **CircleCI → User Settings → Personal API Tokens**, regenerate the token, and update it in **SureCloud → Integrations → CircleCI → Edit Connection**.

</details>

<details>

<summary>Pipelines from some projects are not appearing in SureCloud</summary>

SureCloud collects pipelines for all projects visible to the token account within the connected organisation. If a project is not appearing, confirm the token account has been added to that project's team in CircleCI. Projects with restricted access may require explicit membership.

</details>

<details>

<summary>Job-level details are missing for some workflows</summary>

Job details are only available for workflows that have completed or are in a terminal state. Running or queued workflows will have incomplete job data. SureCloud collects job details for completed workflows only. Re-run SureCloud's data collection after the relevant workflows have completed.

</details>


---

# 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://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/circleci.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.