Jenkins integration

With the Allure Report plugin for Jenkins, you can add an "Allure Report" step to your build configuration, so that Jenkins will generate a test report automatically for each build.

The plugin supports both Allure 2 (Java-based, installed as a Jenkins global tool) and Allure 3 (Node.js-based, resolved from PATH on the agent). You choose which version to use per job.

Installation and configuration

To enable Allure support in your Jenkins installation, do the following under the administrator account:

1. install the plugin,
2. set up the report generation tool.

1. Install the plugin

The recommended method of installing the Allure Report plugin is via the Jenkins web interface. However, if your Jenkins configuration does not have access to the internet, you can install the plugin by uploading an HPI file to Jenkins manually. The selected installation method does not affect the functionality of the plugin.

To install the plugin from the internet directly:

1. In the Jenkins web interface, go to Manage Jenkins → Plugins → Available plugins.

2. Using the search box, find the "Allure" plugin. Check the checkbox next to the plugin.

3. Click Install without restart.

   On the Download progress page, wait until each status is "Success".

To install the plugin via a file:

1. On the Releases page for Allure Report plugin, find the version you want to choose (the latest version is recommended) and click direct link. Save the HPI file to a local directory on your device.

2. In the Jenkins web interface, go to Manage Jenkins → Plugins → Advanced settings.

3. Under the Deploy Plugin section, click Browse and select the HPI archive from your device.

4. Click the Deploy button to confirm the installation.

   On the Download progress page, wait until each status is "Success".

After the installation, the plugin will appear in the Manage Jenkins → Plugins → Installed plugins section.

2. Set up the report generation tool

The setup depends on which version of Allure you plan to use.

Allure 3 (Node.js-based)

Allure 3 expects the allure command to be available in the PATH on each Jenkins agent where reports will be generated.

To set up Allure 3 on Jenkins agents:

1. On each agent that will generate Allure 3 reports, install the Allure CLI via npm:

   npm install -g allure

2. Verify the installation:

   allure --version

INFO

An Allure 3 (from PATH) installations section is available under Manage Jenkins → Tools. This section is an artifact of the Jenkins Tool management system, requires no configuration, and has no effect — the plugin always resolves the allure command from the system PATH automatically. You can safely ignore this section.

Allure 2 (Java-based)

Allure 2 is installed as a Jenkins global tool. Once added, Jenkins takes care of downloading it to every agent that needs to build a report.

Quick Setup (recommended for internet-connected instances):

The easiest way to configure Allure 2 is to use the Quick Setup button, which appears automatically in the job configuration whenever no Allure 2 installation has been set up yet.

1. Open any job's Configure page and add an Allure Report post-build action (see Using Allure in a freestyle project).

2. Under the Allure Report section, if no Allure 2 installation is configured, a warning banner will appear. Click Quick Setup (Install Latest Stable Allure 2).

   INFO

   The Quick Setup button is only visible to Jenkins administrators.

   Jenkins will download the latest stable release of Allure 2 from Maven Central and register it as a global tool. The tool will be downloaded to each agent on first use.

To install the tool manually (internet-connected):

1. In the Jenkins web interface, go to Manage Jenkins → Tools.

2. Under the Allure Commandline installations section, click Add Allure Commandline.

   Make sure that the Install automatically checkbox is checked.

3. From the installer dropdown, select From Maven Central (legacy).

4. Fill in the fields:

   • Name — a name to help you recognize this version of the tool, e.g., "2.39.0".
   • Version — the release of Allure Report to install. The latest version is recommended.

5. Click Save.

To install the tool from a custom URL (air-gapped environments):

1. In the allure-commandline directory at Maven Central, find the latest ZIP or TAR.GZ archive. Copy it to a web server that is available to the Jenkins server.

2. In the Jenkins web interface, go to Manage Jenkins → Tools.

3. Under the Allure Commandline section, click Add Allure Commandline.

   Make sure that the Install automatically checkbox is checked.

4. Click X to remove the existing installer block.

5. Click Add installer → Extract *.zip/*.tar.gz.

6. Fill in the fields:

   • Name — a name to help you recognize this version of the tool, e.g., "2.39.0".
   • Download URL for binary archive — the URL from which the utility will be downloaded.
   • Subdirectory of extracted archive — leave empty.

7. Click Save.

Updating Allure integration

TIP

Updating Allure in Jenkins requires updating not just the Allure plugin itself, which only manages the Jenkins integration, but also the report generation tool, which is the actual Allure Report software.

Furthermore, we recommend updating the tool from time to time even if there are no pending plugin updates, as the tool usually gets more frequent updates than the plugin.

1. Update the plugin

To update via Jenkins interface:

1. In the Jenkins web interface, go to Manage Jenkins → Plugins.
2. Click on the Updates tab.
3. If the Allure plugin appears in the list, check the checkbox next to "Allure".
4. Click Update.
5. On the next page, check Restart Jenkins when installation is complete and no jobs are running.
6. Wait for Jenkins to restart automatically.

To update manually via HPI file:

1. Visit the Allure Report plugin releases page.
2. Download the latest .hpi file.
3. In Jenkins, go to Manage Jenkins → Plugins → Advanced settings.
4. Under "Deploy Plugin", click Browse and select your downloaded HPI file.
5. Click Deploy.
6. Restart Jenkins when prompted.

2. Update the report generation tool

Allure 3

To update Allure 3, run the following command on each agent where it is installed:

npm update -g allure

Allure 2

If the tool was installed from the internet directly:

1. Go to Manage Jenkins → Tools.
2. Find your existing Allure Commandline configuration in the Allure Commandline section.
3. Click on the tool name to expand its configuration.
4. Update the Version field to the latest Allure version (e.g., change from "2.34.0" to "2.39.0").
5. Optionally, update the Name field to reflect the new version.
6. Click Save.

If the tool was installed from a custom URL:

1. Go to Manage Jenkins → Tools.
2. Find your existing Allure Commandline configuration.
3. Update the Download URL for binary archive to point to the newer version at your mirror or at Maven Central.
4. Optionally, update the Name field to reflect the new version.
5. Click Save.

Using Allure in a freestyle project

In Jenkins, a "freestyle project" is a build configuration for which you add and edit steps via the web interface. With the Allure Report plugin, the web interface gets an option to add a post-build action for building test reports.

1. In the Jenkins web interface, select a job you want to enable Allure Report for.

2. In the menu on the left, click Configure.

   INFO

   Before continuing, make sure that the build configuration:

   • contains a step that runs the project's tests,
   • has the Allure adapter enabled for its test framework.

3. Under the Post-build Actions section, click Add post-build action → Allure Report.

4. In the Allure Version dropdown, select the version of Allure to use:

   • Allure 2 (Java-based, auto-installed) — uses a Jenkins global tool; requires a configured Allure Commandline installation (see Set up the report generation tool).
   • Allure 3 (Node.js-based, requires 'allure' in PATH) — uses the allure command from the agent's PATH; requires Allure 3 to be installed on the agent via npm.

5. In the Results → Path field, specify the path to the test results directory (see How it works).

   TIP

   If you have multiple build steps generating test results into multiple directories, use the Add button to specify more paths.

6. If you have more than one Allure 2 installation configured and are using Allure 2, use the Allure CLI Installation dropdown to select which one to use. If only one installation is configured, it is selected automatically.

7. Click Advanced if you need to configure any of the following:

   • JDK — the JDK to use for report generation. Applies to Allure 2 only.
   • Allure Configuration — path to a configuration file for report generation. Applies to Allure 3 only.

8. Click Save.

After the configuration, you can click Build Now to run the build configuration.

Using Allure in a Jenkins Pipeline script

If you store the job in a Jenkins Pipeline script, you can use the allure command to define a step for building test reports. It is recommended to use the Jenkins web interface for generating the command with the appropriate parameters.

1. In Jenkins, select a job you want to enable upload for.

2. In the menu on the left, click Pipeline Syntax.

   An interface for generating code snippets for Jenkins Pipeline will open.

3. In the Sample Step dropdown list, select "allure: Allure Report".

4. In the Allure Version dropdown, select Allure 2 or Allure 3 as needed.

5. In the Results → Path field, specify the path to the test results directory (see How it works).

   TIP

   If you have multiple build steps generating test results into multiple directories, use the Add button to specify more paths.

6. If you are using Allure 2 and you have more than one Allure 2 installation configured, use the Allure CLI Installation dropdown to select which one to use.

7. Click Generate Pipeline Script.

   In the area below the button, the generated command will appear. For Allure 2, for example:

   allure includeProperties: false,
          jdk: '',
          results: [[path: 'build/allure-results']]

   For Allure 3:

   allure allureVersion: '3',
          includeProperties: false,
          results: [[path: 'build/allure-results']]

   Copy the generated command into clipboard.

8. Open the Groovy script that you use for the project. It may be:

   • the script in the text box in (job) → Configure → Pipeline,
   • the Jenkinsfile under the project's version control system (see the official documentation).

   INFO

   Before continuing, make sure that the build configuration:

   • contains a step that runs the project's tests,
   • has the Allure adapter enabled for its test framework.

9. Paste the generated command into the appropriate place of the script.

   For Declarative Pipelines

   // If you use the [Declarative Pipeline syntax](https://www.jenkins.io/doc/book/pipeline/syntax/#declarative-pipeline), find the stage that runs the tests and insert a new `always` block into that stage's `post` block. This will make Allure Report run after the test launch regardless of how many tests succeeded.
   pipeline {
       agent any
   
       stages {
           stage('Build') {
               steps {
                   git 'https://github.com/eroshenkoam/allure-example.git'
                   sh './gradlew clean test'
               }
               post {
                   always {
                       allure includeProperties: false,
                              jdk: '',
                              results: [[path: 'build/allure-results']]
                   }
               }
           }
       }
   }

   For Scripted Pipelines

   // If you use the [Scripted Pipeline syntax](https://www.jenkins.io/doc/book/pipeline/syntax/#scripted-pipeline), there are a lot of ways to organize the pipeline code in such a way that Allure Report runs after the tests, regardless of their results. One way to do so is to wrap all existing steps in a `try` statement, with the generated `allure` command placed in the `finally` block.
   node {
       stage('Build') {
           try {
               git 'https://github.com/eroshenkoam/allure-example.git'
               sh './gradlew clean test'
           }
           finally {
               allure includeProperties: false,
                      jdk: '',
                      results: [[path: 'build/allure-results']]
           }
       }
   }

10. Save the script. In the case of a Jenkinsfile, make sure to commit the changes to the repository.