Skip to end of metadata
Go to start of metadata
You are viewing documentation of TeamCity 7.x, which is not the most recently released version of TeamCity. Please refer to the listing to choose another version.

Table of Contents

Note that you can create new Maven-based build configuration automatically from specified pom.xml, and set up a dependency build trigger, if specific Maven artifact has changed.


Remote Run Limitations related to Maven runner
As a rule, a personal build in TeamCity doesn't affect any "regular" builds run on TeamCity server and its results are visible to its initiator only. However, in case of using Maven runner, this behavior may differ.
TeamCity doesn't interfere anyhow with Maven dependencies model. Hence, if your Maven configuration deploys artifacts to a remote repository, they will be deployed there even if you run a personal build. Thereby, a personal build may affect builds that depend on your configuration.
For example, you have a configuration A that deploys artifacts to a remote repository and these artifacts are used by configuration B. When a personal build for A has finished, your personal artifacts will appear in B. This can be especially injurious, if configuration A is to produce release-version artifacts, because proper artifacts will be replaced with developer's ones, which will be hard to investigate because of Maven versioning model. Plus these artifacts will become available to all dependent builds, not only those managed by TeamCity.
To avoid this, we recommend not using remote run for build configurations which perform deployment of artifacts.

Below you can find reference information about the Maven2 Build Runner fields:

Maven Parameters




In the Goals field, specify the sequence of space-separated Maven goals that you want TeamCity to execute.
Some Maven goals can use version control systems, and, thus, they may become incompatible with some VCS checkout modes. If you want TeamCity to execute such goal:

  • Select "Automatically on agent" in the VCS checkout mode drop-down list on the Version Control Settings page. This makes the version control system available to a goal execution software.

Path to a POM file

Specify path to the POM file relative to the build working directory.
By default, the property contains a pom.xml file. If you leave this field blank, the same value is put in this field. The path may also point to a subdirectory, and as such <subdirectory>/pom.xml is used.


Alternatively, click to choose the file using VCS repository browser (Currently VCS repository browser is only available for Git, Mercurial, Subversion and Perforce. )

Additional Maven command line parameters

Specify the list of command line parameters.


The following parameters are ignored: -q, -f, -s (if User settings path is provided)

Working directory

Specify the Build working directory, if it differs from the build checkout directory.

Maven Home

In Maven selection field choose Maven version you want to use. By default the path to Maven installation is taken from the M2_HOME environment variable, otherwise the bundled Maven 3 is used.
Alternatively, you can set it as %MAVEN_HOME% environment variable right on a build agent.

User Settings

Specify what kind of user settings to use here. This is equivalent to Maven command line option -s or --settings. The available options are:


Settings are taken from the default location (chosen by Maven).

User settings path

Enter the path to an alternative user settings file.

Predefined settings

If there are settings filed uploaded to TeamCity server you can select here, which of those files to use. To upload a user settings file to TeamCity, click Manage settings files.
You can upload Maven user settings files at any time at Administration | Maven Settings tab. The uploaded files are stored under <TeamCity Data Directory>/config/_mavenSettings directory. If necessary, they can be edited right there.

Java Parameters

JDK Home Path

The path to JDK Home is read from the *JAVA_HOME* environment variable or *JDK home* specified on the build agent if you leave this field empty. If these two values are not specified as well, TeamCity uses the JDK home on which the build agent process is started.

JVM command line parameters

Specify JVM command line parameters, for example, maximum heap size or parameters enabling remote debugging. These values are passed by the JVM used to run your build. For example:

Local Artifact Repository Settings

Select Use own local repository for this build configuration to isolate this build configuration's artifacts repository from other local repositories.

Incremental Building

Select Build only modules affected by changes check box to enable incremental building of Maven modules. The general idea is that if you have a number of modules interconnected by dependencies, a change most probably affects (directly or transitively) only some of them, so if we build only affected modules and take the result of building the rest of the modules from the previous build we will have the overall result equal to the result of building the whole project from scratch with less effort and faster.

Since Maven itself has very limited support for incremental builds, TeamCity uses its own change impact analysis algorithm for determining the set of affected modules and uses a special preliminary phase for making dependencies of the affected modules.

First TeamCity performs own change impact analysis taking into account parent relationship and different dependency scopes and determines affected modules. Then the build is split into two sequential Maven executions.

The first Maven execution called preparation phase is intended for building the dependencies of affected modules. The preparation phase is to assure there will be no compiler or other errors during the second execution caused by absence or inconsistency of dependency classes.

The second Maven execution called main phase executes the main goal (for example, test), thus performing only those tests affected by the change.

Code Coverage

Coverage support based on IDEA coverage engine is added to Maven runner. To learn about configuring code coverage options, please refer to the Configuring Java Code Coverage page.


Note: only Surefire version 2.4 and higher is supported.


If you have several build agents installed on the same machine, by default they use the same local repository. However there are two ways to designate custom local repository to each build agent:

  • Specify the following property in the teamcity-agent/conf/
    For instance,
  • Run each build agent under different user account.

See also: