# CI/CD integration

Source: https://docs.qualflare.com/docs/cli/ci-cd · Last updated: 2026-11-08

Upload test results to Qualflare from GitHub Actions, GitLab CI/CD, Jenkins, Azure Pipelines or any CI with the qf CLI: tokens, variables and branch detection.

To upload test results to Qualflare from any CI/CD pipeline, run `qf login <identifier> --force` with the access token in `QF_TOKEN`, then `qf <identifier> collect <report>` after your tests; qf reads the branch and commit that GitHub Actions, GitLab CI/CD, Jenkins and Bitbucket Pipelines set.

After a later CI execution uploads successfully, [compare it with an earlier run](https://docs.qualflare.com/docs/runs/analyze-results#comparing-to-previous-runs) to review matching cases and choose the next investigation.

## Choose your CI provider

Each CI provider has its own page with a complete pipeline, the secret setup and what to set for branch detection.

- [GitHub Actions](https://docs.qualflare.com/docs/cli/ci-cd/github-actions): qualflare-action or the qf CLI in a workflow, with a QF_TOKEN repository secret.
- [GitLab CI/CD](https://docs.qualflare.com/docs/cli/ci-cd/gitlab-ci): A report job in .gitlab-ci.yml that runs when the test job fails.
- [Jenkins](https://docs.qualflare.com/docs/cli/ci-cd/jenkins): A Jenkinsfile stage with a Secret text credential named QF_TOKEN.
- [Azure Pipelines](https://docs.qualflare.com/docs/cli/ci-cd/azure-pipelines): An azure-pipelines.yml step with a secret variable, and QF_BRANCH set from the build.
- [CircleCI](https://docs.qualflare.com/docs/cli/ci-cd/circleci): A config.yml step with when: always, and QF_BRANCH set from CIRCLE_BRANCH.
- [Bitbucket Pipelines](https://docs.qualflare.com/docs/cli/ci-cd/bitbucket-pipelines): An after-script in bitbucket-pipelines.yml with a secured QF_TOKEN variable.
- [Other CI systems](https://docs.qualflare.com/docs/cli/ci-cd/other-ci): Travis CI, the Docker image, npx and self-hosted runners.

On Travis CI or any other CI system, see [Other CI systems, Docker and npx](https://docs.qualflare.com/docs/cli/ci-cd/other-ci): the same two commands, with the values [Branch and commit detection](https://docs.qualflare.com/docs/cli/ci-cd#auto-detection) lists.

## How a CI upload works

Every CI integration follows the same two commands:

```bash
qf login <identifier> --force
qf <identifier> collect test-results/*.xml
```

1. `qf login --force` reads the token from the `QF_TOKEN` environment variable and saves it without prompting, which a non-interactive CI job needs.
2. `qf <identifier> collect` uploads the results.

Store the token as a CI secret named `QF_TOKEN` and expose it to the job as an environment variable. Don't pass the token as an argument: the process list shows it.

Each provider page wraps this flow in its own YAML or Groovy:

```mermaid
flowchart LR
    Runner["Test Runner<br/>(pytest, Jest, JUnit, ...)"] -->|writes| Report["Report File<br/>(JUnit XML / JSON)"]
    Login["qf login ci --force"] -->|saves token| Collect["qf ci collect"]
    Report --> Collect
    Collect -->|uploads| Qualflare[("Qualflare")]
    Qualflare --> Launch["Launch appears"]
```

Use `ci` as the identifier in CI pipelines — it's short and descriptive.

### Before you begin

* A project access token with **Allow writes** off, which you create in **Project Settings** > **Access Tokens** (requires the Editor role or higher in the project). See [Access Tokens](https://docs.qualflare.com/docs/api/access-tokens).
* An environment that exists in the project. `QF_ENVIRONMENT` defaults to `development`, and an upload that names an environment the project doesn't have fails. See [Environments](https://docs.qualflare.com/docs/runs/environments).
* A report file your test runner writes, in one of the [supported formats](https://docs.qualflare.com/docs/cli/formats).

The manual install steps on the provider pages pin qf 0.7.0. qualflare-action installs the latest qf unless you set its `version` input.

## Run the upload when tests fail

`qf <identifier> collect` exits 0 when the upload succeeds, whether or not tests failed, so the test step decides the job's result. Run the upload step even when the test step fails:

| Provider                                                                                             | What keeps the upload running                                                        |
| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| [GitHub Actions](https://docs.qualflare.com/docs/cli/ci-cd/github-actions#usage)                     | `if: ${{ !cancelled() }}` on the upload step                                         |
| [GitLab CI/CD](https://docs.qualflare.com/docs/cli/ci-cd/gitlab-ci#when-tests-fail)                  | `when: always` on the upload job, and `artifacts: when: always` on the test job      |
| [Jenkins](https://docs.qualflare.com/docs/cli/ci-cd/jenkins#when-tests-fail)                         | `catchError(buildResult: 'FAILURE', stageResult: 'FAILURE')` around the test command |
| [Azure Pipelines](https://docs.qualflare.com/docs/cli/ci-cd/azure-pipelines#when-tests-fail)         | `condition: always()` on the upload step                                             |
| [CircleCI](https://docs.qualflare.com/docs/cli/ci-cd/circleci#when-tests-fail)                       | `when: always` on the upload step                                                    |
| [Bitbucket Pipelines](https://docs.qualflare.com/docs/cli/ci-cd/bitbucket-pipelines#when-tests-fail) | the upload in the step's `after-script`                                              |
| [Travis CI](https://docs.qualflare.com/docs/cli/ci-cd/other-ci#travis-ci)                            | the upload in `after_script`                                                         |

Don't let the test step itself pass on failure: GitHub's `continue-on-error: true` turns the job and the pull request check green. A failed upload exits with 1, or with 3, 4, 5 or 7 for an API error: see [exit codes](https://docs.qualflare.com/docs/cli/collect#exit-codes).

## Environment variables

In CI, set qf's options as `QF_` environment variables on the job or step; a command-line flag still wins over them.

### Configuration priority

Values are applied in the following order (highest to lowest priority):

1. **CLI flags** (`--environment`, `--branch`, etc.)
2. **Environment variables** (`QF_*`)
3. **The report file**: the environment and platform a native reporter wrote into its report
4. **Auto-detection**: CI platform variables, then the local git checkout (branch and commit only)
5. **Built-in defaults**

### QF environment variables

| Variable             | Purpose                                                                                                                             | Default         | Example                       |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------- | ----------------------------- |
| `QF_TOKEN`           | Access token, read only by `qf login` when no token argument is given                                                               | *(none)*        | Your CI secret                |
| `QF_ENVIRONMENT`     | Identifier of an environment that exists in the project                                                                             | `development`   | `production`, `staging`, `qa` |
| `QF_BRANCH`          | Git branch name                                                                                                                     | *Auto-detected* | `main`, `feature/login`       |
| `QF_COMMIT`          | Git commit SHA                                                                                                                      | *Auto-detected* | `a1b2c3d4e5f6...`             |
| `QF_MILESTONE`       | Milestone sequence number to link the launch to. Values below `1` are ignored, and the milestone must exist in the project.         | *(none)*        | `3`                           |
| `QF_RETRY_MAX`       | Maximum number of retry attempts                                                                                                    | `3`             | `5`                           |
| `QF_RETRY_DELAY`     | Base delay between retries (Go duration format)                                                                                     | `1s`            | `2s`, `500ms`                 |
| `QF_RETRY_MAX_DELAY` | Maximum delay between retries (Go duration format)                                                                                  | `30s`           | `60s`                         |
| `QF_TIMEOUT`         | Timeout for each HTTP request attempt (Go duration format). The overall `collect` deadline is the `--timeout` flag (default `30s`). | `120s`          | `60s`, `2m`                   |
| `QF_VERBOSE`         | Enable verbose output                                                                                                               | `false`         | `true`, `1`                   |
| `QF_QUIET`           | Suppress non-error output                                                                                                           | `false`         | `true`, `1`                   |

See [Configuration and environment variables](https://docs.qualflare.com/docs/cli/configuration) for the full reference.

### Duration format

Duration-related variables (`QF_RETRY_DELAY`, `QF_RETRY_MAX_DELAY`, `QF_TIMEOUT`) use Go duration format:

| Unit         | Suffix | Examples          |
| ------------ | ------ | ----------------- |
| Seconds      | `s`    | `30s`, `90s`      |
| Milliseconds | `ms`   | `500ms`, `1500ms` |
| Minutes      | `m`    | `1m`, `5m`        |

## Branch and commit detection

qf records each launch's branch and commit from the first of these variables that has a value:

| Value  | Read from, in order                                                                    | Then                   |
| ------ | -------------------------------------------------------------------------------------- | ---------------------- |
| Branch | `QF_BRANCH`, `GIT_BRANCH`, `GITHUB_REF_NAME`, `CI_COMMIT_REF_NAME`, `BITBUCKET_BRANCH` | The local git checkout |
| Commit | `QF_COMMIT`, `GIT_COMMIT`, `GITHUB_SHA`, `CI_COMMIT_SHA`, `BITBUCKET_COMMIT`           | The local git checkout |

If none of these is set, `collect` reads the branch and commit from the local git checkout. A detached HEAD, which many CI checkouts use, gives no branch, so set `QF_BRANCH` or pass `--branch` there.

| CI system                                                                                              | Branch                                                               | Commit             | What to set                                                                                                                          |
| ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| GitHub Actions                                                                                         | `GITHUB_REF_NAME`                                                    | `GITHUB_SHA`       | On `pull_request` runs, see [Pull request branches](https://docs.qualflare.com/docs/cli/ci-cd#pull-request-branches) |
| GitLab CI/CD                                                                                           | `CI_COMMIT_REF_NAME`                                                 | `CI_COMMIT_SHA`    | Nothing                                                                                                                              |
| Jenkins (Git plugin)                                                                                   | `GIT_BRANCH`                                                         | `GIT_COMMIT`       | `QF_BRANCH` when `GIT_BRANCH` holds a remote prefix such as `origin/main`                                                            |
| [Bitbucket Pipelines](https://docs.qualflare.com/docs/cli/ci-cd/bitbucket-pipelines#branch-and-commit) | `BITBUCKET_BRANCH`                                                   | `BITBUCKET_COMMIT` | Nothing                                                                                                                              |
| Azure Pipelines                                                                                        | None: no Azure variable is read, and the checkout is a detached HEAD | The local checkout | `QF_BRANCH` from `Build.SourceBranch`                                                                                                |
| [CircleCI](https://docs.qualflare.com/docs/cli/ci-cd/circleci#branch-and-commit)                       | The local checkout (no CircleCI variable is read)                    | The local checkout | `QF_BRANCH` and `QF_COMMIT` from `CIRCLE_BRANCH` and `CIRCLE_SHA1`                                                                   |
| [Travis CI](https://docs.qualflare.com/docs/cli/ci-cd/other-ci#travis-ci)                              | The local checkout (a detached HEAD: no branch)                      | The local checkout | `QF_BRANCH` and `QF_COMMIT` from `TRAVIS_*`                                                                                          |
| Any other                                                                                              | The local checkout                                                   | The local checkout | `QF_BRANCH` on a detached HEAD                                                                                                       |

### Pull request branches on GitHub Actions

On `pull_request` events, `GITHUB_REF_NAME` is `<number>/merge` and `GITHUB_SHA` is the merge commit GitHub creates, so the launch would record that branch and commit instead of the pull request's own. Set both from the pull request:

```yaml
env:
  QF_BRANCH: ${{ github.head_ref || github.ref_name }}
  QF_COMMIT: ${{ github.event.pull_request.head.sha || github.sha }}
```

On other events `head_ref` is empty, so both fall back to the pushed branch and commit. Where this goes in a workflow: [GitHub Actions](https://docs.qualflare.com/docs/cli/ci-cd/github-actions#branch-and-commit).

## Security best practices

### Token management

* **Never hardcode tokens** in your repository
* Always use your CI/CD platform's secret/variable management
* Use one token per pipeline. Each token belongs to one project, so you can revoke a leaked token without breaking other pipelines.
* Leave **Allow writes** off for CI tokens. Uploading results does not need it.
* Tokens expire after at most 90 days. [Rotate the CI token](https://docs.qualflare.com/docs/cli/ci-cd/rotate-tokens) before it stops working ([Access Tokens](https://docs.qualflare.com/docs/api/access-tokens)).

- [Rotate the CI access token](https://docs.qualflare.com/docs/cli/ci-cd/rotate-tokens): Replace an expiring token: create the new one, update the secret, run once, revoke the old one.

### Check for leaked tokens

Add a pre-commit hook to catch accidentally committed tokens:

```bash
#!/bin/bash
# .git/hooks/pre-commit

# Qualflare access tokens start with qfp_ followed by 49 more characters
if git diff --cached --name-only | xargs grep -lE 'qfp_[A-Za-z0-9_-]{49}' 2>/dev/null; then
    echo "ERROR: Possible Qualflare access token in staged files!"
    echo "Remove the token before committing."
    exit 1
fi
```

Tokens created before the `qfp_` prefix existed have no prefix, so this check cannot catch them.

## Troubleshooting

### Login fails in CI

Ensure the token value is correct and not empty:

```yaml
- run: |
    [ -n "$QF_TOKEN" ] || { echo "QF_TOKEN is not set"; exit 1; }
    qf login ci --force
```

With no token argument and an empty `QF_TOKEN`, `qf login` reads standard input instead, and an empty token fails with `Error: token cannot be empty`. The guard line stops the job first, with a clear message.

### Upload fails with timeout

Raise the overall upload deadline with `--timeout` (default `30s`):

```bash
qf ci collect results.xml --timeout 2m
```

`QF_TIMEOUT` (default `120s`) only caps each single HTTP request. Raise it as well only if one request takes longer than two minutes.

### Retry failures

Adjust retry settings for unreliable networks:

```yaml
env:
  QF_RETRY_MAX: 5
  QF_RETRY_DELAY: 2s
  QF_RETRY_MAX_DELAY: 60s
```

Retries run inside the `--timeout` deadline (default `30s`), so raise it with them, for example `qf ci collect results.xml --timeout 5m`.

### Branch or commit not detected

Manually override if auto-detection fails. The [Branch and commit detection](https://docs.qualflare.com/docs/cli/ci-cd#auto-detection) table names the variable to set on each CI, such as `QF_BRANCH` on Azure Pipelines or any detached HEAD.

### Identifier already exists on a reused runner

On a self-hosted runner that keeps its home directory between jobs, a second `qf login` of the same identifier without `--force` fails with:

```text
Error: identifier "ci" already exists; cannot prompt because stdin is not a terminal — use --force to overwrite
```

`qf login <identifier> --force` overwrites the saved token, as every `qf login` command in these pages' examples does. qualflare-action does the same from v1.0.3, which `@v1` runs; a workflow pinned to an earlier tag fails here ([Version pinning](https://docs.qualflare.com/docs/cli/ci-cd/github-actions#version-pinning)).

For every exit code and API error, see [Troubleshoot qf and CI uploads](https://docs.qualflare.com/docs/cli/troubleshooting).

## Advanced usage

### Conditional upload

Only upload on specific branches:

```yaml
- name: Upload to Qualflare
  if: github.ref == 'refs/heads/main'
  env:
    QF_TOKEN: ${{ secrets.QF_TOKEN }}
  run: |
    qf login ci --force
    qf ci collect results.xml
```

### Multiple test files

Upload multiple test result files:

```bash
# All XML files
qf ci collect test-results/*.xml

# Specific files
qf ci collect unit-tests.xml integration-tests.xml
```

One `collect` call is one launch, and the files in it merge into that launch. For parallel jobs, see [Sharded runs](https://docs.qualflare.com/docs/cli/sharding).

### Dry run in CI

Test your CI configuration without actually uploading:

```yaml
- name: Validate test results (dry run)
  env:
    QF_TOKEN: ${{ secrets.QF_TOKEN }}
  run: |
    qf login ci --force
    qf ci collect results.xml --dry-run
```

Note: `--dry-run` does not upload to Qualflare, so the token does not need to be valid — but the identifier must still be registered locally with `qf login`.

`qf validate` checks report files with no token at all: see the [qf command reference](https://docs.qualflare.com/docs/cli/commands#validate-command).

## Related

* **Guides:** [GitHub Actions](https://docs.qualflare.com/docs/cli/ci-cd/github-actions) · [GitLab CI/CD](https://docs.qualflare.com/docs/cli/ci-cd/gitlab-ci) · [Jenkins](https://docs.qualflare.com/docs/cli/ci-cd/jenkins) · [Azure Pipelines](https://docs.qualflare.com/docs/cli/ci-cd/azure-pipelines) · [CircleCI](https://docs.qualflare.com/docs/cli/ci-cd/circleci) · [Bitbucket Pipelines](https://docs.qualflare.com/docs/cli/ci-cd/bitbucket-pipelines) · [Other CI systems, Docker and npx](https://docs.qualflare.com/docs/cli/ci-cd/other-ci) · [Setting up CI for an open-source project](https://docs.qualflare.com/docs/open-source/ci-setup) · [Rotate the CI access token](https://docs.qualflare.com/docs/cli/ci-cd/rotate-tokens)
* **Reference:** [Upload results with qf collect](https://docs.qualflare.com/docs/cli/collect) · [Configuration](https://docs.qualflare.com/docs/cli/configuration) · [qf command reference](https://docs.qualflare.com/docs/cli/commands)
* **CLI/API:** [Access Tokens](https://docs.qualflare.com/docs/api/access-tokens)
