# Jenkins

Source: https://docs.qualflare.com/docs/cli/ci-cd/jenkins · Last updated: 2026-10-27

Upload test results from a Jenkins pipeline to Qualflare with the qf CLI: a Jenkinsfile stage, a QF_TOKEN secret text credential and GIT_BRANCH detection.

To upload test results from Jenkins to Qualflare, add a stage that runs `qf <identifier> collect <report>` after your tests, with the access token stored as a Secret text credential with the ID `QF_TOKEN`; qf reads `GIT_BRANCH` and `GIT_COMMIT` from the Git plugin.

## 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).
* A report file your test stage writes, such as JUnit XML. The examples use `ci` as the identifier.

## Store the token as a credential

1. Go to **Manage Jenkins** > **Manage Credentials**
2. Select your domain (typically "Global")
3. Click **Add Credentials** > **Secret text**
4. Secret: Your Qualflare access token
5. ID: `QF_TOKEN`
6. Click **Create**

## Add the upload stage

Add a stage to your `Jenkinsfile`:

```groovy
pipeline {
    agent any

    stages {
        stage('Test') {
            steps {
                // Mark the build failed but keep going, so the upload stage still runs
                catchError(buildResult: 'FAILURE', stageResult: 'FAILURE') {
                    sh 'pytest --junitxml=results.xml'
                }
            }
            post {
                always {
                    junit 'results.xml'
                }
            }
        }

        stage('Upload to Qualflare') {
            steps {
                // Install qf CLI (run once or bake into your agent image)
                sh '''
                    if ! command -v qf &> /dev/null; then
                        VERSION=0.4.0
                        curl -L "https://github.com/qualflare/qualflare-cli/releases/download/v${VERSION}/qf_${VERSION}_linux_amd64.tar.gz" -o qf.tar.gz
                        tar -xzf qf.tar.gz && mv qf /usr/local/bin/
                    fi
                '''

                // Upload to Qualflare
                withCredentials([string(credentialsId: 'QF_TOKEN', variable: 'QF_TOKEN')]) {
                    sh '''
                        qf login ci --force
                        export QF_BRANCH="${GIT_BRANCH#origin/}"  # drop the remote name Jenkins may add
                        qf ci collect results.xml
                    '''
                }
            }
        }
    }
}
```

See the official [Jenkins Pipeline documentation](https://www.jenkins.io/doc/book/pipeline/) for `Jenkinsfile` syntax and pipeline concepts beyond what's shown here.

## Branch and commit

qf reads the branch from `GIT_BRANCH` and the commit from `GIT_COMMIT`, which the Jenkins Git plugin sets. `GIT_BRANCH` can hold the remote name, such as `origin/main`, and qf stores it as it is: the `export` line in the upload stage strips it. In a multibranch pipeline, you can set `QF_BRANCH` from `BRANCH_NAME` instead.

## Run the upload when tests fail

`catchError(buildResult: 'FAILURE', stageResult: 'FAILURE')` around the test command keeps the build failed and lets the upload stage run. `junit 'results.xml'` in `post { always }` keeps Jenkins' own test report.

## Parallel jobs

One `qf <identifier> collect` call is one launch, and several files in one call merge into it. With Jenkins `parallel` stages, gather every stage's report and upload them all from one later stage with `--shard`: see [Sharded runs](https://docs.qualflare.com/docs/cli/sharding).

## Pin the qf version

The example installs qf 0.4.0 through `VERSION=0.4.0`. To pin another release, set `VERSION` to a version from the [qf releases page](https://github.com/qualflare/qualflare-cli/releases).

## Troubleshooting

`Error: token cannot be empty` means `QF_TOKEN` was empty when `qf login` ran: the credential ID must be `QF_TOKEN`, and the qf commands must run inside `withCredentials`. More fixes: [Troubleshooting](https://docs.qualflare.com/docs/cli/ci-cd#troubleshooting) on CI/CD integration.

## Related

* **Guides:** [CI/CD integration](https://docs.qualflare.com/docs/cli/ci-cd)
* **Reference:** [Upload results with qf collect](https://docs.qualflare.com/docs/cli/collect) · [Configuration](https://docs.qualflare.com/docs/cli/configuration)
* **CLI/API:** [Access Tokens](https://docs.qualflare.com/docs/api/access-tokens)