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

<CardGroup cols={3}>
  <Card title="GitHub Actions" icon="git-branch" href="/run-tests-ci-github-actions">
    Gate pull requests or pushes with a Qodex workflow.
  </Card>

  <Card title="GitLab CI" icon="git-branch" href="/run-tests-ci-gitlab">
    Add Qodex as a pipeline job for merge requests and main.
  </Card>

  <Card title="CircleCI" icon="circle" href="/run-tests-ci-circleci">
    Trigger Qodex from a CircleCI job and fail the workflow on failure.
  </Card>

  <Card title="Buildkite" icon="hammer" href="/run-tests-ci-buildkite">
    Run Qodex from a Buildkite step and gate downstream deploys.
  </Card>

  <Card title="Jenkins" icon="server" href="/run-tests-ci-jenkins">
    Add Qodex to a declarative Jenkins pipeline.
  </Card>

  <Card title="Generic shell" icon="terminal" href="/run-tests-ci-generic-shell">
    Use a portable curl and jq script in any CI system.
  </Card>
</CardGroup>

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

<CardGroup cols={2}>
  <Card title="Run tests via webhook" icon="webhook" href="/run-tests-via-webhook">
    Understand the webhook API used by CI.
  </Card>

  <Card title="Run tests on a schedule" icon="calendar-clock" href="/run-tests-on-schedule">
    Create schedule webhooks for preconfigured runs.
  </Card>
</CardGroup>