TeamCity 2020.1 Help

Maven

The Maven build runner allows using Apache Maven for automating builds.

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

Maven runner settings

Option

Description

Goals

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 Configuring VCS Settings. If you want TeamCity to execute such a 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 the goal execution software. To use the release:prepare goal with Perforce VCS, see the section below.

Path to POM file

Specify the 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.

Additional Maven command line parameters

Specify the list of command line parameters.

Working directory

Specify the Build Working Directory if it differs from the build checkout directory.

Maven Settings

Choose the Maven version you want to use. Since TeamCity 2017.1, you can manage the installed versions.

<Auto>

The path to Maven installation is taken from the M2_HOME environment variable, otherwise the current default version is used.

<Default>

The bundled version 3.2.5 is used as default. Since TeamCity 2017.1, you can change the defaults.

<Custom>

Provide a path to a custom Maven version.

User Settings

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

<Default>

Settings are taken from the default Maven locations on the agent. For the server logic, see Maven Server-Side Settings.

<Custom>

Enter the path to an alternative user settings file. The path should be valid on agent and also on the server, see Maven Server-Side Settings.

Predefined settings

If there are settings files uploaded to the TeamCity server via the administration UI, you can select one of the available options here. To upload settings file to TeamCity, click Manage settings files. Maven settings are defined on the project level. You can see the settings files defined in the current project or upload files on the Project Settings page using Maven Settings. The files will be available in the project and its subprojects. The uploaded files are stored in the <TeamCity Data Directory>/config/projects/%projectID%/pluginData/mavenSettings directory. If necessary, they can be edited right there. The uploaded files are used both for the agent and server-side Maven functionality.
If Custom or Predefined settings are used, the path to the effective user settings file is available inside the maven process as the teamcity.maven.userSettings.path system property.

Java Parameters

Option

Description

JDK

Select a JDK. This section details the available options. The default is JAVA_HOME environment variable or the agent's own Java.

JDK home path

The option is available when <Custom> is selected above. Use this field to specify the path to your custom JDK used to run the build. If the field is left blank, the path to JDK Home is read either from the JAVA_HOME environment variable on agent the computer, or from the env.JAVA_HOME property specified in the build agent configuration file (buildAgent.properties ). If these values are not specified, TeamCity uses the Java home of the build agent process itself.

JVM command line parameters

You can specify such 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.

Example:

-Xmx512m -Xms256m

Local Artifact Repository Settings

Select one of the following options:

Option

Description

Per agent (default)

Use a separate repository to store artifacts, produced by all builds run by an agent, under the agent system directory.

Per build configuration

Use a separate repository to store artifacts, produced by all builds of the current build configuration.

Maven default

Use the default Maven repository location. The repository is shared between all build configurations and all agents on the machine.

The runner will use the location specified in the additional command-line parameter -Dmaven.repo.local. If the parameter is not specified, it will search for values set in settings.xml.

Incremental Building

Select the Build only modules affected by changes checkbox to enable incremental building of Maven modules.
The general idea of incremental building is to process only changed modules without spending time on reprocessing unchanged modules they are connected with. TeamCity utilizes this method to run tests only for changed Maven modules thus saving time when rerunning a build or a build chain.

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 the affected modules. The preparation phase is to assure there will be no compiler or other errors during the second execution caused by the 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.

Also, check the related blog post on the topic.

Docker Settings

In this section, you can specify a Docker image which will be used to run the build step.

Code Coverage

The Maven build runner supports code coverage based on the IDEA coverage engine. To learn about configuring code coverage options, refer to the Configuring Java Code Coverage page.

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 allocate a custom local repository to each build agent:

  • Specify the following property in the teamcity-agent/conf/buildAgent.properties:

system.maven.repo.local=%system.agent.work.dir%/<subdirectory_name>

For instance, %system.agent.work.dir%/m2-repository.

  • Run each build agent under different user account.

Maven Release with Different VCSs

To run the release:prepare Maven task with different VCS's supported by TeamCity, make sure you're using at least 2.0 version of the Maven Release Plugin.

Using Maven Release with Perforce

Check the following:

  1. Use ticket-based authentication for Maven Release plugin.

  2. Make sure that your release:prepare Maven task works when it is run from the command line without TeamCity.

In the Perforce VCS Root Settings of your build configuration in TeamCity:

  1. Enable the checkout on agent.

  2. Enable Use ticket-based authentication in Perforce VCS root settings.

  3. Make sure your build agent environment doesn't have any occasional P4 variables which can interfere with the execution of Maven Release Plugin.

  4. Specify release:prepare in the Goals field of the Maven build step and run the build.

Using Maven Release with Git VCS

  1. Use Git SSH URL as SCM URL in your pom.xml.

  2. Make sure that your release:prepare maven task works when it is run from the command line without TeamCity.

On the TeamCity agent:

1. Make sure that the agent has Git installed and added to the agent's $PATH on Unix-like OS's and to the %PATH% environment variable on Windows.

2. On the agent, set your account's identity by executing

git config --system user.email "buildserver@example.com" git config --system user.name "TeamCity Server"

3. Make sure your Git VCS is added to the known hosts database on the agent.

On the TeamCity server:

1. Upload Git SSH key to your TeamCity server.

In the settings for your build configuration in TeamCity:

2. On the Version Control Settings page, enable the checkout on agent.

3. In your Git VCS root, enable Private Key authentication.

4. Add the SSH Agent build feature to your configuration.

5. Specify release:prepare in the Goals field of the Maven build step and run the build.

Last modified: 20 November 2020