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.

Installation and configuration

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

1. install the plugin,
2. install the global 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. Install the global tool

The second necessary part of the installation process is adding the Allure command-line utility to Jenkins as a “global tool”. Once added, Jenkins will take care of downloading the utility to every machine that needs to build a test report.

The Allure Report plugin provides an easy way to download and add the latest version of the global tool from the official Allure server. However, if your Jenkins configuration does not have access to the internet, you can set up a custom URL from which the utility will be downloaded.

To install the tool from the internet directly:

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, and the options block for From Maven Central is shown.

3. Fill in the fields:

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

4. Click Save.

To install the tool from a custom URL:

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 From Maven Central 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.24.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 global tool, which is the actual Allure Report software.

Furthermore, we recommend updating the global 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 global tool

After updating the plugin, you need to update the global tool to match:

If 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.23.0" to "2.24.0").
5. Optionally, update the Name field to reflect the new version.
6. Click Save.

If 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 downloaded from 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 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.

5. If you have more than one version of the Allure global tool installed (see Install the global tool), click Advanced and make sure that the proper version is selected in Commandline.

6. 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 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.

5. If you have more than one version of the Allure global tool installed (see Install the global tool), click Advanced and make sure that the proper version is selected in Commandline.

6. Click Generate Pipeline Script.

   In the area below the button, the generated command will appear, for example:

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

   Copy the generated command into clipboard.

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

8. 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']]
           }
       }
   }

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