> 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/gitlab-ci.md).

# GitLab CI

## Quick answer

Prepare GitLab CI/CD variables, stages, environments, 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 GitLab CI/CD job to coordinate a ContextQA test-plan run and require its result before a merge or deployment.

## Before you begin

* Create and manually validate the test plan you want to use as the gate.
* Open the plan's **CI / CD** tab and confirm GitLab 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 GitLab configuration

Open **Settings → CI/CD → Variables** and add:

| Key                      | Recommended settings                         | Value                                                         |
| ------------------------ | -------------------------------------------- | ------------------------------------------------------------- |
| `CONTEXTQA_API_TOKEN`    | Masked; protected for protected environments | The one-time token value copied from ContextQA                |
| `CONTEXTQA_TEST_PLAN_ID` | Protected when appropriate                   | The plan ID shown on the ContextQA plan overview              |
| `CONTEXTQA_API_BASE_URL` | Protected when appropriate                   | The public base URL from the official contract, when supplied |

Use environment scopes when staging and production use different plans or credentials. Do not store a ContextQA username or password in GitLab CI/CD variables.

## Design the pipeline stage

Place the ContextQA job after the target environment is ready and before the protected deployment or release job. When the public contract is available, the job should:

1. Start the plan with the published method, path, and payload.
2. Capture the returned run ID.
3. Poll the published status operation with a bounded timeout.
4. Exit successfully only for documented success results.
5. Include the run ID in the job output or a dotenv artifact for later stages.

Use `rules` to run a small plan for merge requests and a broader plan for protected branches or deployment pipelines. If the gate is required, do not mark the job `allow_failure: true`.

## Protect the release path

After testing both pass and fail behavior:

1. Require the pipeline to succeed before merge.
2. Restrict production variables to protected branches and environments.
3. Require approvals for changes to the CI configuration that controls the gate.
4. Rotate the API token before expiry and after suspected exposure.

## Troubleshooting

**There is no endpoint to place in `.gitlab-ci.yml`**

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

**The token is unavailable in a merge-request pipeline**

Check the variable's Protected and environment-scope settings against the pipeline source and target branch.

**A failed plan does not block a merge**

Confirm the job returns a non-zero exit code, is not allowed to fail, and is included in the project's merge checks.

## 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)
* [CircleCI](/integrations/circleci.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/gitlab-ci.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.