Jenkins

Jenkins integration connects Jenkins jobs with Allure TestOps: uploads test results during a build using the Jenkins plugin, lets TestOps trigger Jenkins builds, and maps Jenkins parameters to launch environments.

The plugin is required for both directions: it handles result upload via the withAllureUpload() wrapper and enables the TestOps-to-Jenkins trigger path. Without the plugin installed, TestOps cannot start Jenkins pipelines.

Before you begin

• Permission to install plugins and manage global settings in Jenkins.
• The URL of the TestOps instance and the numeric TestOps project ID.
• A Jenkins user account that can create an API token for the trigger path.

1. Install the Jenkins plugin

The Allure TestOps Jenkins plugin comes in two release lines. Choose based on your Jenkins version and Java runtime:

• Plugin v4 — for Jenkins 2.361.1 and later, requires Java 17 on Jenkins agents.
• Plugin v3 — for Jenkins earlier than 2.361.1, requires Java 11.

If the plugin version and the Java runtime on an agent do not match, the plugin will not start and result upload will fail on that agent.

Download both release lines from dl.qameta.io.

Install from a URL

1. Open dl.qameta.io and copy the URL of the HPI file for the plugin version that matches your environment.
2. In Jenkins, go to Manage Jenkins → Manage Plugins → Advanced settings.
3. Under Deploy Plugin, paste the copied URL.
4. Click Deploy and wait until each status on the Download progress page is Success.

Install from an HPI file

1. Download the HPI file for the matching plugin version from dl.qameta.io.
2. In Jenkins, go to Manage Jenkins → Manage Plugins → Advanced settings.
3. Under Deploy Plugin, click Browse and select the downloaded HPI file.
4. Click Deploy and wait until each status on the Download progress page is Success.

2. Send results from Jenkins to TestOps

Create the TestOps token

1. In Allure TestOps, click your avatar and open API Tokens.
2. Click + Token.
3. Enter a name for the token, for example Token for Jenkins, and click Create.
4. Copy the generated token.

Register the TestOps server in Jenkins

1. In Jenkins, go to Manage Jenkins → System.
2. Under Allure, click Add Allure Server → Allure Server.
3. Fill in the fields:
   • ID — a recognizable name for the TestOps instance.
   • Endpoint — the URL of the TestOps instance.
4. Next to the Credentials field, click Add → Jenkins.
5. In the dialog that appears, fill in the fields:
   • Kind — Secret text
   • Secret — the API token copied from TestOps
   • ID — a recognizable credential name, for example testops-credentials
6. Click Add to close the dialog.
7. In the Credentials drop-down, select the credential you just created.
8. If your TestOps instance uses a self-signed SSL certificate, uncheck Enable certificate validation.
9. Click Test connection. A "Successfully authorized as <username>" message confirms the credentials are correct.

1. Click Save at the bottom of the page.

Configure a freestyle job

1. In Jenkins, select the job and click Configure.

2. Under Build Environment, check Allure: upload results.

3. Fill in the fields:

   • Server — the TestOps server registered in Jenkins.
   • Project — the numeric TestOps project ID.
   • Launch name — a template for naming the launch. You can use any Jenkins environment variable (see /env-vars.html on your Jenkins instance for the full list).
   • Launch tags — optional comma-separated tags.

4. Click Add results → Results.

5. In the Path field, specify the path to the Allure results directory, for example build/allure-results. For multiple directories, click Add again for each additional path.

   The Jenkins plugin does not support wildcards or glob patterns in the Path field.

6. Click Advanced to configure additional parameters:

   • Silent mode — if checked, a connection failure when uploading results will not fail the job. Use only if you have another way to view test results.
   • Index Existing Files — if checked, TestOps uploads all files in the results directory, even those not modified during this run.

7. Click Save.

Configure a pipeline job

Use Pipeline Syntax to generate a withAllureUpload() snippet:

1. In Jenkins, select the job and click Pipeline Syntax.
2. In the Sample Step drop-down, select withAllureUpload: Allure: upload results.
3. Fill in the same fields as for a freestyle job (Server, Project, Launch name, Launch tags, Results path).
4. Click Generate Pipeline Script and copy the generated snippet.
5. In the Jenkinsfile or inline pipeline script, wrap the test command with the generated block.

pipeline {
    agent any

    stages {
        stage('Build') {
            steps {
                git 'https://github.com/example/repo.git'
                withAllureUpload(
                    name: '${JOB_NAME} - #${BUILD_NUMBER}',
                    projectId: '1',
                    results: [[path: 'build/allure-results']],
                    serverId: 'Allure TestOps production',
                    tags: ''
                ) {
                    sh './gradlew clean test'
                }
            }
        }
    }
}

node {
    stage('Build') {
        git 'https://github.com/example/repo.git'
        withAllureUpload(
            name: '${JOB_NAME} - #${BUILD_NUMBER}',
            projectId: '1',
            results: [[path: 'build/allure-results']],
            serverId: 'Allure TestOps production',
            tags: ''
        ) {
            sh './gradlew clean test'
        }
    }
}

The withAllureUpload() block must surround the command that actually runs the tests. If placed outside the test step, Jenkins may build successfully while TestOps receives no results.

Verify the upload

After the next build finishes:

1. In Jenkins, open Build History and click the latest build.

2. In the build menu and at the bottom of the build page there should be links to the TestOps launch.

   

3. Open that launch in TestOps and confirm test results are present.

4. Open a single result and confirm it links back to the Jenkins build.

   

3. Let TestOps trigger Jenkins builds

Add the global Jenkins integration

An instance administrator should:

1. Open Administration → Integrations.
2. Click + Add integration.
3. Select Jenkins.
4. Fill in the fields:
   • Name — a recognizable name, for example Jenkins production.
   • Endpoint — the URL of the Jenkins instance, for example https://jenkins.example.com/.
5. If the Jenkins instance uses a self-signed SSL certificate, check Disable certificate validation.
6. Click Add integration.

Create a Jenkins API token

1. In Jenkins, click your username and go to Security.
2. Under API Token, click Add new Token.
3. Enter a recognizable name, for example Token for Allure TestOps, and click Generate.
4. Click the Copy icon to copy the generated token.

Add Jenkins credentials to the TestOps project

1. In TestOps, open the target project and go to Settings → Integrations.
2. Under Available integrations, find the Jenkins integration and click Add integration.
3. Fill in the fields:
   • Username — your Jenkins username.
   • API token — the token generated in Jenkins.
4. Click Test connection. A "Connection established" message confirms the credentials are correct.
5. Click Add integration.

Configure the Jenkins-backed job in TestOps

After the first successful upload, TestOps creates the Jenkins-backed job automatically:

1. Open Jobs in the project.

2. Click ⋯ next to the job and select Configure.

3. Fill in the fields:

   • Name — a stable display name.
   • Build server — the global Jenkins integration added by the administrator.
   • Job can be used to run tests — enable to allow triggering from TestOps.
   • Parameters — see Section 4.

   

4. Click Submit.

4. Pass parameters and branch values

Jenkins parameterized builds let TestOps pass runtime values such as branch, browser, or target environment, and make those values visible on launches triggered outside TestOps.

Set default values in Jenkins

1. In Jenkins, select the job and click Configure.

2. Under General, check This project is parameterized.

3. For each parameter, click Add Parameter → String Parameter and fill in:

   • Name — the variable name.
   • Default Value — the value to use when not overridden for a specific launch.

4. Click Save.

   

Add global environment names

An instance administrator should:

1. Open Administration → Environment.

2. For each parameter, click + Create, enter the name, and click Submit.

   

Map parameters in the project

1. In the project, open Settings → Environment.

2. For each parameter, click + Create (or the edit icon if it already exists):

   • Mapping key — the Jenkins parameter name from Step 1.
   • Environment variable — the global parameter name created by the administrator.

3. Click Submit.

   

Add parameters to the job

1. Open Jobs and click the Refresh button next to the job.

   The parameter names and their default values from Jenkins should appear in the job description.

   

2. Click ⋯ next to the job and select Configure.

3. In the Parameters section, for each parameter select the corresponding global environment variable.

   

4. Click Submit.

If the project has multiple branches, add a Branch environment variable in Allure TestOps and map it to the Jenkins parameter that controls branch selection. This special name instructs Jenkins which branch to use when TestOps triggers the build.

Troubleshooting

"Could not create session for closed launch" in the log

Jenkins pipeline jobs have no unique identifier beyond their name. If a pipeline is deleted and recreated with the same name, the plugin cannot upload results because that name is already associated with a closed launch in TestOps.

Rename the recreated pipeline to a new unused name, then run the upload again.

UnsupportedClassVersionError during upload

Problem: The build log contains an error similar to:

java.lang.UnsupportedClassVersionError: .../jenkins/callable/UploadResultsCallable has been
compiled by a more recent version of the Java Runtime (class file version 61.0),
this version of the Java Runtime only recognizes class file versions up to 55.0

Followed by:

Caused: hudson.remoting.ProxyException: .../jenkins/AllurePluginException: Could not stop uploader

Reason: The installed plugin version does not match the Java runtime on the Jenkins agent. Plugin v4 requires Java 17 (class file version 61). Plugin v3 requires Java 11 (class file version 55).

Solution: Install the plugin version that matches the Java runtime on your agents. For Jenkins 2.361.1 and later, use plugin v4 with Java 17 on all agents. Make sure the Java version on agents matches the Jenkins controller.

Related pages

• CI systems
• allurectl
• Jobs
• Environment
• Ecosystem overview