---
title: TeamCity integration
description: Learn how to integrate Allure Report with TeamCity. Install the plugin, configure the command-line tool, and automate test report generation for your builds.
---

# TeamCity integration (Allure 2)

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

## Installation and configuration

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

1. [install the plugin](#_1-install-the-plugin),
2. [install the command-line tool](#_2-install-the-command-line-tool),
3. [configure serving artifacts](#_3-configure-serving-artifacts) (optional).

### 1. Install the plugin

The recommended method of installing the Allure Report plugin is to use the one-click installation feature in JetBrains Marketplace. However, if your TeamCity configuration does not have access to the internet, you can install the plugin by uploading a ZIP archive to TeamCity manually. The selected installation method does not affect the functionality of the plugin.

**To install the plugin from JetBrains Marketplace directly:**

1. In the TeamCity web interface, go to **Administration → Plugins** and click **Browse plugins repository**.

1. In the dialog that appears, click **Proceed**.

   This will enable the one-click installation feature for JetBrains Marketplace in your browser.

1. On the [Allure Report plugin page in JetBrains Marketplace](https://plugins.jetbrains.com/plugin/20544-allure-report), click **Get → Install to ⟨hostname⟩**.

1. Click **Install** to confirm the installation.

1. Click **Enable uploaded plugin**.

1. In the dialog that appears, click **Enable** to confirm the plugin activation.

**To install the plugin via a ZIP archive:**

1. On the [Allure Report plugin page in JetBrains Marketplace](https://plugins.jetbrains.com/plugin/20544-allure-report), click **Get → Download**. Save the ZIP archive to a local directory on your device.

1. In the TeamCity web interface, go to **Administration → Plugins** and click **Upload plugin zip**.

1. In the dialog that appears, select the ZIP archive from your device.

1. Click the **Upload plugin zip** button to confirm the installation.

1. Click **Enable uploaded plugin**.

1. In the dialog that appears, click **Enable** to confirm the plugin activation.

After the installation, the plugin will appear in the list under the **External plugins** section.

![Allure TeamCity plugin install](/images/integrations/teamcity/allure-plugin.png "Allure TeamCity plugin install")

### 2. Install the command-line tool

The second necessary part of the installation process is adding the Allure command-line utility to TeamCity as an “agent tool” (see the [official TeamCity documentation](https://www.jetbrains.com/help/teamcity/installing-agent-tools.html)). Once added, TeamCity will take care of distributing the utility to every machine (“agent”) that needs to build a test report.

The Allure Report plugin provides an easy way to download and add the latest version of the command-line tool from the official Allure server. However, if your TeamCity configuration does not have access to the internet, you can add the tool by uploading a ZIP archive to TeamCity manually. The selected installation method does not affect the functionality of the plugin.

**To install the tool from the internet directly:**

1. In the TeamCity web interface, go to **Administration → Tools** and click **Install Tool**.

1. In the dialog that appears, select the **Allure** option.

1. Select the **Download** option.

1. Select the latest version of the Allure command-line utility from the dropdown list.

1. Click **Add**.

**To install the tool via a ZIP archive:**

1. In the [allure-commandline directory at Maven Central](https://repo.maven.apache.org/maven2/io/qameta/allure/allure-commandline/), find and download the latest ZIP archive to a local directory on your device.

   Warning:
   Make sure to save the archive as **allure-commandline-⟨version⟩.zip**, for example: **allure-commandline-2.24.0.zip**. TeamCity may not recognize the command-line tool correctly if it has a different name.

1. In the TeamCity web interface, go to **Administration → Tools** and click **Install Tool**.

1. In the dialog that appears, select the **Allure** option.

1. Select the **Upload** option.

1. Select the ZIP archive from your device.

1. Click **Add**.

After the installation, the version of the command-line tool will appear in the list under the **Allure** section.

![Allure TeamCity plugin configure Allure Commandline](/images/integrations/teamcity/allure-commandline.png "Allure TeamCity plugin configure Allure Commandline")

### 3. Configure serving artifacts

Info:
This step is required if you prefer the test reports to be available for browsing without downloading.
If you prefer them to be available only as downloadable ZIP archives, skip this step.

By default, TeamCity does not allow browsing the HTML artifacts generated by external plugins. This principle is called “artifacts domain isolation” (see the [official TeamCity documentation](https://www.jetbrains.com/help/teamcity/2022.10/teamcity-configuration-and-maintenance.html#artifacts-domain-isolation)). However, if you configure an additional domain for this purpose, TeamCity will let users browse the artifacts on that domain. This is the recommended approach.

Alternatively, you can disable the artifacts domain isolation. In this case, TeamCity will let users browse the HTML artifacts, including Allure test reports, on the main domain of the TeamCity installation.

**To enable viewing test reports on a separate domain:**

1. In the TeamCity web interface, go to **Administration → Global Settings**.

1. Under the **Artifacts Domain Isolation** section, check the **Enable isolation protection** checkbox.

   Warning:
   This setting applies to all the projects in your TeamCity installation, which may be considered unsafe for some projects.

1. Enter the **Artifacts URL**.

   Make sure to use a domain that is configured to point to the same IP address as the main TeamCity server URL.

1. Click **Save**.

**To enable viewing test reports on the TeamCity domain:**

1. In the TeamCity web interface, go to **Administration → Global Settings**.

1. Under the **Artifacts Domain Isolation** section, uncheck the **Enable isolation protection** checkbox.

1. Click **Save**.

## Using Allure in a UI-based build configuration

1. In the TeamCity web interface, go to **Projects**.

1. In the tree on the left, select a project and a build configuration.

1. On the top of the page, click **Edit configuration**.

1. Select the **Build Steps** section.

   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. Click **Add build step**.

1. On the runner type selection screen, select **Allure Report**.

1. Fill the build step creation form.

   - **Step name** — any name to identify the report building step, e.g., “Generate test report”.

   - **Execute step** — “Even if some of the previous steps failed”.

   - **Result directory** — the path to the directory in which the Allure integration test framework saves the test results.

     Most Allure integrations save the test results into `allure-results` unless specifically configured otherwise. For more details, check the “Run tests” section of the documentation for your [Allure integration](/docs/frameworks/).

   - **Report directory** — the name of the directory in which Allure should generate the HTML report. Note that the directory name cannot contain the slash character.

   - **Allure** — the version of the Allure command-line tool to build the test report with. The list of available options includes the versions installed on the [step 2](#_2-install-the-command-line-tool).

     It is recommended to use the latest available version.

   - **Publish mode**:

     - “Publish archived report” — Allure will create an `allure-report.zip` archive containing a directory which will be named according to the **Report directory** setting.
     - “Publish plain report” — Allure will create a directory named according to the **Report directory** setting.

1. Click **Save**.

After the configuration, you can click **Run** to run the build configuration.

## Using Allure in a DSL-based build configuration

If you use the [Configuration as Code](https://www.jetbrains.com/teamcity/features/configuration-as-code/) approach and store the build configuration in a [Kotlin DSL](https://www.jetbrains.com/help/teamcity/2023.05/kotlin-dsl.html) script, you can enable building test reports by copying a new `step` object into your `.teamcity/settings.kts` file. The new step must be placed after all the steps that run the tests.

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.

Inside the `step` object, define the properties:

- `name` — any name to identify the report building step, e.g., “Generate test report”.

- `type` — `allureReportGeneratorRunner`.

- `executionMode` — `BuildStep.ExecutionMode.RUN_ON_FAILURE`.

Use the `param()` function to set additional parameters for the Allure Report step. If a parameter is not set, its default value will be used.

- `allure.version` — the version of the Allure command-line tool to build the test report with. It is recommended to use the latest available version.

  Set the parameter to `%teamcity.tool.allure-⟨version⟩%` to use a specific version of the command-line utility, foe example: `%teamcity.tool.allure-2.24.0%`.

  Skip this parameter or set it to `%teamcity.tool.allure.DEFAULT%` to use the version that is selected as the default one in the **Administation → Tools** section.

- `allure.result.directory` — the path to the directory in which the Allure integration test framework saves the test results.

  Most Allure integrations save the test results into `allure-results` unless specifically configured otherwise. For more details, check the “Run tests” section of the documentation for your [Allure integration](/docs/frameworks/).

  Defaults to `allure-results`.

- `allure.report.path.prefix` — the name of the directory in which Allure should generate the HTML report. Note that the directory name cannot contain the slash character.

  Defaults to `allure-report`.

- `allure.publish.mode`:

  - `ARCHIVE` — Allure will create an `allure-report.zip` archive containing a directory which will be named according to the `allure.report.path.prefix` setting.
  - `PLAIN` — Allure will create a directory named according to the `allure.report.path.prefix` setting.

  Defaults to `ARCHIVE`.

Here's an example of a project's `.teamcity/settings.kts` file:

```kotlin
import jetbrains.buildServer.configs.kotlin.*
import jetbrains.buildServer.configs.kotlin.buildSteps.python

version = "2022.10"

project {
    buildType(Build)
}

object Build : BuildType({
    name = "Build"

    vcs {
        root(DslContext.settingsRoot)
    }

    steps {
        python {
            environment = venv {}
            command = pytest {}
        }
        step {
            name = "Generate test report"
            type = "allureReportGeneratorRunner"
            executionMode = BuildStep.ExecutionMode.RUN_ON_FAILURE
            param("allure.version", "%teamcity.tool.allure-2.24.0%")
            param("allure.result.directory", "allure-results")
            param("allure.report.path.prefix", "allure-report")
            param("allure.publish.mode", "PLAIN")
        }
    }
})
```