> ## Documentation Index
> Fetch the complete documentation index at: https://qodex.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Run tests in CI

> Trigger Qodex from your CI pipeline so merges and deploys are gated by the same scenarios you run in the product.

# Run tests in CI

CI runs let Qodex become part of your release process. A pipeline can trigger a Qodex run, wait for the result, and fail the job if scenarios fail.

Use CI runs for pull-request smoke checks, pre-deploy gates, post-deploy production smoke, or scheduled policies that you want a pipeline to fire on demand.

## How CI triggering works

Most CI integrations follow the same shape:

1. Store a Qodex API key as a CI secret.
2. POST to the Qodex webhook trigger endpoint.
3. Read the returned `testRunId`.
4. Poll the test run until it reaches a terminal state.
5. Exit non-zero if the Qodex run failed or timed out.

The run result is still visible in Qodex with the same artifacts, failure classification, and findings as a manual run.

## Choose a trigger style

| Trigger | Use it when |
| - | - |
| Project webhook | The CI job should choose environment, tags, or callback URL dynamically. |
| Schedule webhook | The CI job should fire one preconfigured schedule. |

Project webhooks use a bearer API key. Schedule webhooks use the secret baked into the URL.

## Provider recipes

> [card] [GitHub Actions](https://qodex.ai/docs/run-tests-ci-github-actions.md)
>
> Gate pull requests or pushes with a Qodex workflow.

> [card] [GitLab CI](https://qodex.ai/docs/run-tests-ci-gitlab.md)
>
> Add Qodex as a pipeline job for merge requests and main.

> [card] [CircleCI](https://qodex.ai/docs/run-tests-ci-circleci.md)
>
> Trigger Qodex from a CircleCI job and fail the workflow on failure.

> [card] [Buildkite](https://qodex.ai/docs/run-tests-ci-buildkite.md)
>
> Run Qodex from a Buildkite step and gate downstream deploys.

> [card] [Jenkins](https://qodex.ai/docs/run-tests-ci-jenkins.md)
>
> Add Qodex to a declarative Jenkins pipeline.

> [card] [Generic shell](https://qodex.ai/docs/run-tests-ci-generic-shell.md)
>
> Use a portable curl and jq script in any CI system.

## Recommended setup

* Use one API key per CI environment, such as `github-actions-staging` or `buildkite-prod`.
* Store keys only in the provider's secret store.
* Run `smoke` or `critical` tags on pull requests.
* Run broader `regression` or full-suite checks on main, nightly schedules, or release candidates.
* Always poll to completion before marking the CI job green.

## Example trigger body

```json theme={null}
{
  "environment": "staging",
  "tags": ["smoke"]
}
```

The same scenario can run against a different environment by changing only the `environment` value.

## Related

> [card] [Run tests via webhook](https://qodex.ai/docs/run-tests-via-webhook.md)
>
> Understand the webhook API used by CI.

> [card] [Run tests on a schedule](https://qodex.ai/docs/run-tests-on-schedule.md)
>
> Create schedule webhooks for preconfigured runs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.