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.
note
This build runner has some Remote Run limitations.
This video guide explains how to get the best from platform-specific build runners: it uses Maven as an example.
Option | Description |
---|---|
Goals | Specify the sequence of space-separated Maven goals that you want TeamCity to execute. Some Maven goals can use version control systems, thus they may become incompatible with some VCS checkout modes. |
Path to POM file | Specify the path to the POM file relative to the build working directory. |
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. |
tip
When TeamCity discovers a Maven build step automatically, it sets the goal automatically to
clean test
and an additional Maven command-line parameter-Dmaven.test.failure.ignore
totrue
to ignore failed tests. This parameter is helpful when thetest
goal is used for a Maven project with multiple modules. With this property set totrue
, even if the tests fail in some module, all the following modules will be tested as well.
If you change the goal fromtest
todeploy
(or any other sequential goal from the Maven build lifecycle:package
,verify
, orinstall
), make sure to set-Dmaven.test.failure.ignore
tofalse
so the failed tests are not ignored.
Choose the Maven version you want to use. You can also manage the installed versions.
Setting | Description |
---|---|
<Auto> | The path to the Maven installation is taken from the |
<Default> | The bundled version is used as default. See how to change the defaults. |
<Custom> | Provide a path to a custom Maven version. |
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:
Option | Description |
---|---|
<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 the 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 |
Option | Description |
---|---|
JDK | Select a JDK. This section details the available options. The default is |
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 |
JVM command line parameters | Additional JVM command line parameters allow you to set initial and maximum heap sizes, enable additional logging, select the required bytecode verifier mode, and more. You can specify both standard (begin with To specify multiple command line parameters, use space as a separator. For example:
|
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 |
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.
In this section, you can specify a Docker image which will be used to run the build step.
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.
note
Only Surefire version 2.4 or later 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 allocate a custom local repository to each build agent:
Specify the following property in
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.
To run the release:prepare
Maven task with different VCSs supported by TeamCity, make sure you are using at least 2.0 version of the Maven Release plugin.
The Maven Release plugin needs a ticket to authenticate in Perforce.
In the Perforce VCS root settings of your build configuration in TeamCity:
Enable the checkout on agent.
Enable Use ticket-based authentication in Perforce VCS root settings.
Make sure your build agent environment doesn't have any occasional P4 variables which can interfere with the execution of Maven Release Plugin.
Specify
release:prepare
in the Goals field of the Maven build step and run the build.
To use this plugin with Git, set a Git SSH URL as SCM URL in your pom.xml
.
On the TeamCity agent:
Make sure 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.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"
Make sure your Git VCS is added to the known hosts database on the agent.
On the TeamCity server:
Upload a Git SSH key to your TeamCity server.
Navigate to Administration | <Your Configuration> to access build configuration settings.
Open the Version Control Settings settings tab.
Enable the checkout on the agent.
In your Git VCS root, enable Private Key authentication.
Add the SSH Agent build feature to your configuration.
Specify
release:prepare
in the Goals field of the Maven build step and run the build.
Remote Run Limitations related to the Maven runner:
As a rule, a personal build in TeamCity doesn't affect any "regular" builds run on the 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 the 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 to those managed by TeamCity.
To avoid this, we recommend not using remote run for build configurations which perform deployment of artifacts.
Thanks for your feedback!