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 → Manage 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 → Manage 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 → Manage 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 → Global Tool Configuration.

2. Under the Allure Commandline 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 → Global Tool Configuration.

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.

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.

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

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

   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:

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

   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
   • For Scripted Pipelines

   If you use the Declarative Pipeline syntax, 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.

   For example:

   Groovy
   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']]
                   }
               }
           }
       }
   }

   If you use the Scripted Pipeline syntax, 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.

   For example:

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