---
title: Maven integration
description: Learn how to integrate Allure Report with Maven. Add the plugin to your pom.xml, generate reports after test runs, and configure Allure 3 or Allure 2 runtimes for local and CI builds.
---

# Maven integration

With the Allure Maven plugin, you can generate Allure reports as part of your Maven build by adding a `<plugin>` block to your `pom.xml`. The plugin supports both **Allure 3** (the default, Node.js-based) and **Allure 2** (Java-based, legacy).

- Requires JDK 17 or newer
- Requires Maven 3.1.1 or newer

## Setting up

Add the plugin to the `<reporting>` section of your `pom.xml`:

```xml
<reporting>
    <plugins>
        <plugin>
            <groupId>io.qameta.allure</groupId>
            <artifactId>allure-maven</artifactId>
            <version>3.0.2</version>
        </plugin>
    </plugins>
</reporting>
```

After that, run your tests to produce Allure result files:

```shell
mvn clean test
```

Your test framework's Allure adapter (e.g. `allure-jupiter`, `allure-testng`) writes raw result files to `target/allure-results/` during the test run. The plugin then reads those files and generates the report.

## Running the plugin as a build plugin

To invoke Allure goals directly (e.g. `mvn allure:report`, `mvn allure:serve`), also declare the plugin in the `<build>` section. Maven only resolves plugin prefixes from `<build>` — a `<reporting>`-only declaration supports `mvn site` but not direct invocations.

```xml
<build>
    <plugins>
        <plugin>
            <groupId>io.qameta.allure</groupId>
            <artifactId>allure-maven</artifactId>
            <version>3.0.2</version>
        </plugin>
    </plugins>
</build>
```

You can also use the `<build>` declaration to bind a goal to a specific lifecycle phase, for example to generate the report automatically during `mvn verify`:

```xml
<build>
    <plugins>
        <plugin>
            <groupId>io.qameta.allure</groupId>
            <artifactId>allure-maven</artifactId>
            <version>3.0.2</version>
            <executions>
                <execution>
                    <phase>verify</phase>
                    <goals>
                        <goal>report</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>
```

## Generating a report

### View the report locally

```shell
mvn allure:serve
```

The plugin generates the report and opens it in a local web server. Press `Ctrl+C` to stop the server when done. For Allure 3, the report is written to the configured report directory (default: `target/site/allure-maven-plugin/`) before the server starts and remains there after it stops.

To use a specific port:

```shell
mvn -Dallure.serve.port=8080 allure:serve
```

To bind the server to a specific network interface (Allure 2 only, accepts an IPv4 address):

```shell
mvn -Dreport.version=2.39.0 -Dallure.serve.host=192.168.1.10 allure:serve
```

`allure.serve.host` is not supported for Allure 3. Use `reportVersion 2.x` if host binding is required.

### Generate a static report

```shell
mvn allure:report
```

The report is written to `target/site/allure-maven-plugin/index.html`.

You can also generate the report as part of the standard Maven site lifecycle:

```shell
mvn site
```

## Plugin goals

| Goal               | Default phase        | Description                                                     |
| ------------------ | -------------------- | --------------------------------------------------------------- |
| `allure:report`    | `site`               | Generates a static HTML report from `allure-results/`           |
| `allure:serve`     | `site`               | Generates a report and opens it in a local web server           |
| `allure:aggregate` | `site`               | Aggregates results from all modules in a multi-module project   |
| `allure:install`   | `generate-resources` | Downloads and caches the Allure CLI without generating a report |

## Selecting the runtime

The `reportVersion` parameter controls which version of Allure is used to generate reports.

| `reportVersion` value | Runtime used              |
| --------------------- | ------------------------- |
| Not set (default)     | Allure 3, version `3.4.1` |
| `3.x` (e.g. `3.4.1`)  | Allure 3                  |
| `2.x` (e.g. `2.39.0`) | Allure 2                  |

**In `pom.xml`:**

```xml
<configuration>
    <reportVersion>3.4.1</reportVersion>
</configuration>
```

**On the command line:**

```shell
mvn -Dreport.version=3.4.1 allure:report
```

Any version string that does not start with `2.` or `3.` is rejected with an error.

## Allure 3 runtime provisioning

For Allure 3, the plugin manages its own Node.js runtime. You do **not** need Node.js installed on your system.

On first use, the plugin downloads Node.js and the Allure package and caches them under `${project.basedir}/.allure` (configurable via `allure.install.directory`). Subsequent runs reuse the cache and skip the download.

### Air-gapped and offline builds

Maven offline mode (`mvn -o`) is supported. If the Node.js runtime and Allure package are already cached, the plugin uses them without network access. If either is missing while offline, the build fails with a clear error.

To pre-populate the cache, run `mvn allure:install` once with network access before switching to offline mode.

### Custom Node.js download location

To download Node.js from a mirror instead of `nodejs.org` (for example, in a restricted network):

```xml
<configuration>
    <nodeDownloadUrl>https://my-mirror.example.com/node/v%s/node-v%s-%s.%s</nodeDownloadUrl>
</configuration>
```

The URL pattern receives four arguments: `{version}`, `{version}`, `{os-classifier}`, `{archive-extension}`.

The plugin also fetches a checksum file from `https://nodejs.org/dist/v{version}/SHASUMS256.txt` to verify the download. If your mirror replaces `nodejs.org`, it must serve this file at the equivalent path — otherwise the build will fail with a checksum error even if the archive itself downloaded successfully.

### Custom Node.js version

The default Node.js version is `24.14.1`. To use a different version:

```xml
<configuration>
    <nodeVersion>22.0.0</nodeVersion>
</configuration>
```

### Custom npm registry

```xml
<configuration>
    <npmRegistry>https://npm.example.com</npmRegistry>
</configuration>
```

### Local Allure 3 package archive

To install Allure 3 from a local `.tgz` or `.tar.gz` archive instead of the npm registry (useful for air-gapped environments or testing custom builds):

```xml
<configuration>
    <packagePath>packages/allure-custom.tgz</packagePath>
</configuration>
```

Relative paths are resolved from the project root. This parameter is only supported for Allure 3.

## Allure 3 configuration

For Allure 3, the plugin reads an `allurerc` config file to customize the report. You can provide it as an auto-detected file at the project root or point to it explicitly.

### Auto-detected config files

The plugin looks for any of the following files at the project root, in this order:

- `allurerc.js`
- `allurerc.mjs`
- `allurerc.cjs`
- `allurerc.json`
- `allurerc.yaml`
- `allurerc.yml`

The first match is used. Example `allurerc.yml`:

```yaml
plugins:
  awesome:
    options:
      reportLanguage: en
```

### Explicit config path

Use `allure.config.path` to point to a config file anywhere on the filesystem. Relative paths are resolved from the project root.

**In `pom.xml`:**

```xml
<configuration>
    <configPath>config/allure3.yml</configPath>
</configuration>
```

**On the command line:**

```shell
mvn -Dallure.config.path=config/allure3.yml allure:report
```

When an explicit path is provided, auto-detection is skipped.

This parameter is only supported for Allure 3.

### Keys managed by the plugin

The plugin always controls `output` and `name` — setting these in your own config has no effect. Everything else in your config is preserved. Plugin-managed defaults (such as `historyPath` and `appendHistory` for history) are only applied when your config does not already set those keys, so your values always take precedence.

## Allure 2 download sources (Allure 2)

For Allure 2, the plugin downloads the CLI using Maven's standard dependency resolution, so your repository mirrors, proxies, and credentials configured in `settings.xml` apply automatically.

### Custom download URL

To download Allure 2 from a custom location (for example, a local mirror in a restricted network):

```xml
<configuration>
    <allureDownloadUrl>https://my-mirror.example.com/allure-%s/allure-%s.zip</allureDownloadUrl>
    <reportVersion>2.39.0</reportVersion>
</configuration>
```

The URL pattern receives the version string twice (once for the directory, once for the filename). This parameter is only supported for Allure 2 — use `nodeDownloadUrl` for the Allure 3 Node.js runtime instead.

`allureDownloadUrl` is also respected by the `allure:install` goal when using Allure 2.

### Proxy support

The plugin respects the proxy settings configured in your Maven `settings.xml`. No additional configuration is needed for Allure 2 downloads or Allure 3 Node.js and npm downloads.

## Trend history

For the `allure:report` goal, the plugin preserves trend history across builds automatically. History is cached in the install directory and carried forward into each new report.

History is **enabled by default**. To disable it:

```xml
<configuration>
    <historyEnabled>false</historyEnabled>
</configuration>
```

Or on the command line:

```shell
mvn -Dallure.history.enabled=false allure:report
```

History preservation applies to `allure:report` only. The `allure:serve` and `allure:aggregate` goals are not affected.

For Allure 3, if your `allurerc` file sets `historyPath` or `appendHistory`, your values take precedence over the plugin's defaults.

## Multi-module projects

For multi-module Maven projects, use `allure:aggregate` to combine results from all modules into one report.

In the parent `pom.xml`:

```xml
<reporting>
    <plugins>
        <plugin>
            <groupId>io.qameta.allure</groupId>
            <artifactId>allure-maven</artifactId>
            <version>3.0.2</version>
            <reportSets>
                <reportSet>
                    <id>aggregate</id>
                    <inherited>true</inherited>
                    <reports>
                        <report>aggregate</report>
                    </reports>
                </reportSet>
            </reportSets>
        </plugin>
    </plugins>
</reporting>
```

Then run:

```shell
mvn site
```

The aggregate goal collects `allure-results/` from each child module and produces a single combined report in the parent's `target/site/allure-maven-plugin/`.

You can also invoke aggregate directly without the site lifecycle:

```shell
mvn -Dreport.version=2.39.0 allure:aggregate
```

### Per-module results directory

If a module writes results to a non-default location, configure it using the `allure.results.directory` property in that module's `pom.xml`:

```xml
<properties>
    <allure.results.directory>my-results</allure.results.directory>
</properties>
```

The aggregate goal reads this property from each module's effective POM. The value must be a relative path (relative to the module's build directory) — absolute paths are rejected.

## Advanced configuration

### Custom results directory

By default, the plugin reads results from `target/allure-results/`. To change it:

```xml
<configuration>
    <resultsDirectory>my-results</resultsDirectory>
</configuration>
```

Or on the command line:

```shell
mvn -Dallure.results.directory=my-results allure:report
```

The value is resolved relative to the Maven build directory (`target`), so `my-results` maps to `target/my-results`. Use an absolute path to point outside the build directory.

### Multiple input directories (`allure:report` only) (Allure 2)

To merge results from multiple directories into one report:

```shell
mvn -Dallure.results.inputDirectories=/path/one,/path/two allure:report
```

### Custom report output directory

```xml
<configuration>
    <reportDirectory>${project.build.directory}/my-report</reportDirectory>
</configuration>
```

Or on the command line:

```shell
mvn -Dallure.report.directory=target/my-report allure:report
```

### Single-file report

To generate a self-contained single HTML file instead of a directory:

```xml
<configuration>
    <singleFile>true</singleFile>
</configuration>
```

This works for both Allure 2 and Allure 3. For `allure:serve`, `singleFile` is ignored — use `allure:report` or `allure:aggregate` to produce a single-file report. Allure 3 serve logs a warning when `singleFile` is set; Allure 2 serve silently ignores it.

### Report generation timeout

The default timeout for report generation is 60 seconds. To extend it:

```xml
<configuration>
    <reportTimeout>300</reportTimeout>
</configuration>
```

The `allure:serve` goal uses a separate timeout (default: 3600 seconds, one hour) that covers both generation and the time the server is running:

```xml
<configuration>
    <serveTimeout>7200</serveTimeout>
</configuration>
```

### Allure properties

The plugin passes properties to Allure at report generation time. You can use these to configure things like issue tracker URL patterns.

**From a properties file** (default lookup path: `report.properties` in the project root, i.e. the directory from which you run Maven):

```properties
allure.issues.tracker.pattern=https://jira.example.com/browse/%s
allure.link.tms.pattern=https://tms.example.com/case/%s
```

**From plugin configuration:**

```xml
<configuration>
    <properties>
        <allure.issues.tracker.pattern>https://jira.example.com/browse/%s</allure.issues.tracker.pattern>
    </properties>
</configuration>
```

**From classpath** (both `allure.properties` and `report.properties` are discovered automatically from the test classpath).

Properties from all sources are merged. Plugin configuration properties take highest precedence. Placeholder values like `${project.version}` in property values are expanded using Maven and system properties.

### Categories

Place a `categories.json` file on the test classpath (e.g. under `src/test/resources/`) to define custom test failure categories. The plugin copies it into the results directory before invoking Allure. This works for both Allure 2 and Allure 3.

### Install directory

The default install directory for the Allure runtime is `${project.basedir}/.allure`. To share one installation across multiple projects or put it outside the project tree:

```xml
<configuration>
    <installDirectory>/opt/allure-cache</installDirectory>
</configuration>
```

Or on the command line:

```shell
mvn -Dallure.install.directory=/opt/allure-cache allure:report
```

## Using in CI

### GitHub Actions

In a GitHub Actions workflow, run your tests and then generate the Allure report. The install directory is cached between workflow runs to avoid re-downloading Node.js and the Allure package on every run.

```yaml
- name: Run tests
  run: mvn test

- name: Cache Allure runtime
  uses: actions/cache@v4
  with:
    path: .allure
    key: allure-${{ hashFiles('pom.xml') }}

- name: Generate Allure report
  run: mvn allure:report

- name: Upload Allure report
  uses: actions/upload-artifact@v4
  with:
    name: allure-report
    path: target/site/allure-maven-plugin/
```

### Jenkins Pipeline

```groovy
pipeline {
    agent any

    stages {
        stage('Test') {
            steps {
                sh 'mvn clean test'
            }
        }
        stage('Report') {
            steps {
                sh 'mvn allure:report'
                publishHTML(target: [
                    reportDir: 'target/site/allure-maven-plugin',
                    reportFiles: 'index.html',
                    reportName: 'Allure Report'
                ])
            }
        }
    }
}
```

Alternatively, if you use the [Allure Jenkins plugin](/docs/integrations-jenkins/), you can let Jenkins generate and display the report itself instead of invoking `allure:report` in the pipeline.

### Sharing the Allure install directory across builds

On CI agents that run multiple projects, point all of them at a shared install directory to avoid redundant downloads:

```shell
mvn -Dallure.install.directory=/var/cache/allure allure:report
```

Or pre-populate the cache once per agent using the `allure:install` goal:

```shell
mvn -Dallure.install.directory=/var/cache/allure allure:install
```