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

# Jenkins

## Quick answer

Prepare Jenkins credentials, pipeline stages, timeouts, and build-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 Jenkins pipeline stage to coordinate a ContextQA test-plan run and map its final result to the build status.

## 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 Jenkins 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 Jenkins configuration

Open **Manage Jenkins → Credentials** and add the ContextQA API token as **Secret text**. Give it a recognizable ID such as `contextqa-api-token`.

Store the remaining values as pipeline or folder configuration:

| Name                     | Value                                                         |
| ------------------------ | ------------------------------------------------------------- |
| `CONTEXTQA_TEST_PLAN_ID` | The plan ID shown on the ContextQA plan overview              |
| `CONTEXTQA_API_BASE_URL` | The public base URL from the official contract, when supplied |

Bind the secret text only inside the ContextQA stage. Do not use a username-and-password credential for this integration.

## Design the pipeline stage

Place the ContextQA stage after the target environment is available and before the release stage. When the public contract is available, the stage should:

1. Bind the API token to a temporary environment variable.
2. Start the plan with the published method, path, and payload.
3. Capture the returned run ID.
4. Poll the published status operation inside a Jenkins `timeout` block.
5. Mark the build unsuccessful for every documented non-success result.
6. Add the run ID to the build description or summary.

Avoid printing response bodies that may contain sensitive test data. Do not construct a result-page URL unless the public response returns one.

## Protect the release path

* Make the deployment stage depend on the ContextQA stage.
* Use a smaller plan for change validation and a broader plan for scheduled or release builds.
* Restrict the credential to the folders and agents that need it.
* Test token expiry, timeout, pass, and fail behavior before making the gate required.

## Troubleshooting

**There is no endpoint to place in the Jenkinsfile**

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

**The credential is masked but the request is unauthorized**

Confirm the token is active, has the required scopes, and is bound from the expected Jenkins credential ID.

**A failed plan leaves the build successful**

Map every documented non-success terminal result to `error(...)` or another failing build outcome, and confirm the release stage cannot run after 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)
* [CircleCI](/integrations/circleci.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/jenkins.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.