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

# CircleCI

## Quick answer

Prepare CircleCI variables, contexts, workflows, and result handling for a ContextQA test-plan quality gate. Use this page to understand when the capability applies, complete its user-facing workflow, and verify the expected result.

## What this page covers

Use a CircleCI job to coordinate a ContextQA test-plan run and turn its final result into a workflow gate.

## Before you begin

* Create and manually validate the test plan you want to run.
* Open the plan's **CI / CD** tab and confirm CircleCI is listed.
* Obtain the current public start and status contract supplied for your workspace.
* Create a dedicated [API token](/administration/api-tokens.md) with the narrowest required scopes.

{% hint style="warning" %}
The verified production **CI / CD** tab does not display public endpoint paths. Do not use older examples based on account-password login or `/testplans/{id}/execute`, and do not copy internal URLs from portal network traffic.
{% endhint %}

## Store CircleCI configuration

For one project, open **Project Settings → Environment Variables**. For reuse across projects, open **Organization Settings → Contexts** and create a restricted context.

Add:

| Variable                 | Recommended handling         | Value                                                         |
| ------------------------ | ---------------------------- | ------------------------------------------------------------- |
| `CONTEXTQA_API_TOKEN`    | Secret or restricted context | The one-time token value copied from ContextQA                |
| `CONTEXTQA_TEST_PLAN_ID` | Project variable             | The plan ID shown on the ContextQA plan overview              |
| `CONTEXTQA_API_BASE_URL` | Project variable             | The public base URL from the official contract, when supplied |

Do not store a ContextQA username or password in CircleCI.

## Design the workflow

Place the ContextQA job after the environment it validates is available and before the protected deployment step. When the public contract is available, the job should:

1. Start the test plan with the published method, path, and payload.
2. Store the returned run ID in the job environment or a workspace file.
3. Poll the published status operation with a bounded timeout.
4. Exit successfully only for documented success results.
5. Print the run ID in the job summary so reviewers can find the run in ContextQA.

Attach a restricted CircleCI context to the job when it contains the API token. Use approval jobs or separate contexts for production environments.

## Choose the trigger

| Workflow event      | Good fit                                   |
| ------------------- | ------------------------------------------ |
| Pull request        | Fast smoke or risk-based plan              |
| Main-branch build   | Post-merge validation                      |
| Deployment workflow | Pre- or post-deployment checks             |
| Scheduled workflow  | Broad regression outside the feedback loop |

Avoid running the same expensive plan on overlapping events unless the duplicate coverage is intentional.

## Troubleshooting

**There is no endpoint to place in `config.yml`**

Obtain the public API contract for your workspace. The current production CI/CD tab describes the start and status operations but does not publish their paths.

**The job cannot read the token**

Confirm the variable or context is attached to the job and that context restrictions permit the current branch or project.

**A failed run does not block deployment**

Ensure the ContextQA job returns a non-zero exit code for every documented non-success result and that the deployment job requires it.

## Related pages

* [Prepare a CI/CD quality gate](/getting-started/ci-cd-tutorial.md)
* [Test Plans](/web-testing/test-plans.md)
* [API tokens](/administration/api-tokens.md)
* [GitHub Actions](/integrations/github-actions.md)
* [GitLab CI](/integrations/gitlab-ci.md)
* [Jenkins](/integrations/jenkins.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://learning.contextqa.com/integrations/circleci.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.