---
title: Jenkins integration
description: Learn how to integrate Allure Report with Jenkins. Install the plugin, configure global tools, and generate automated test reports for your builds.
---

# 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](#_1-install-the-plugin),
2. [set up the report generation tool](#_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**.

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

1. 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](https://plugins.jenkins.io/allure-jenkins-plugin/releases/), 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.

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

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

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

   ```shell
   npm install -g allure
   ```

2. Verify the installation:

   ```shell
   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](#using-allure-in-a-freestyle-project)).

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

1. Under the **Allure Commandline installations** section, click **Add Allure Commandline**.

   Make sure that the **Install automatically** checkbox is checked.

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

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

1. Click **Save**.

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

1. In the [allure-commandline directory at Maven Central](https://repo.maven.apache.org/maven2/io/qameta/allure/allure-commandline/), find the latest ZIP or TAR.GZ archive. Copy it to a web server that is available to the Jenkins server.

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

1. Under the **Allure Commandline** section, click **Add Allure Commandline**.

   Make sure that the **Install automatically** checkbox is checked.

1. Click **X** to remove the existing installer block.

1. Click **Add installer → Extract \*.zip/\*.tar.gz**.

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

1. 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](https://plugins.jenkins.io/allure-jenkins-plugin/releases/).
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:

```shell
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](https://repo.maven.apache.org/maven2/io/qameta/allure/allure-commandline/).
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.

1. 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 integration enabled for its test framework.

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

1. 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](#_2-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.

1. In the **Results → Path** field, specify the path to the test results directory (see [How it works](/docs/how-it-works/)).

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

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

1. 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](/docs/v3/configure/) for report generation. Applies to Allure 3 only.

1. 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](https://www.jenkins.io/doc/book/pipeline/), you can use the [`allure`](https://www.jenkins.io/doc/pipeline/steps/allure-jenkins-plugin/) 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.

1. In the menu on the left, click **Pipeline Syntax**.

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

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

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

1. In the **Results → Path** field, specify the path to the test results directory (see [How it works](/docs/how-it-works/)).

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

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

1. Click **Generate Pipeline Script**.

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

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

   For Allure 3:

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

   Copy the generated command into clipboard.

1. 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](https://www.jenkins.io/doc/book/pipeline/jenkinsfile/)).

   Info:
   Before continuing, make sure that the build configuration:

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

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

   **For Declarative Pipelines:**
   ```groovy
   // 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:**
   ```groovy
   // 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']]
           }
       }
   }
   ```

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