CircleCI

Prepare CircleCI variables, contexts, workflows, and result handling for a ContextQA test-plan quality gate.

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 with the narrowest required scopes.

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.

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
• Test Plans
• API tokens
• GitHub Actions
• GitLab CI
• Jenkins