Issue

What is the best practice for using Maven settings files in Jenkins?

We have a team who wants to have their own Maven configurations and store their own settings file on the agent which will be used to runs Maven builds. Is this recommended?

Environment

Resolution

There are various approaches depending on your needs and constraints.

Manually configure Maven on each agent

Apache Maven builds its local settings from two configuration files as you can see in the settings page:

The Maven install (called global settings): ${maven.home}/conf/settings.xml
A user’s install (called user settings): ${user.home}/.m2/settings.xml

You can store different configuration files on the agent, or even have different Maven installations on the agent. This approach will require careful planning or it could become too complicated as the projects grow.

Use Config File Provider

The Config File Provider plugin lets Jenkins automatically deploy configuration files on the agent before a build starts.
Apache Maven allows redefining the path of these files (-gs,–global-settings and -s,–settings ) from the command line. This is what the Config File Provider plugin uses to specify different files and to avoid conflicts between different jobs settings.

With the Config File Provider plugin you can define your different settings files globally at your Jenkins master level, since version 2.15 you can also define them at a folder level (if you have permissions to configure the folder). With this approach you can delegate the definition of their own settings files to a team. You’ll find that you can inject a Jenkins credential as a server entry in your maven settings thus you can share some credentials across various teams/settings without making their values visible.

The last step is to configure your job to use these settings that are automatically installed by the Config File Provider plugin. With a freestyle job you’ll configure the Config File Provider plugin to install some settings and in the maven command line you’ll use the options -s/-gs to use it. In a Maven job you’ll have the choice in the advanced configuration of the settings to use. In a pipeline job you’ll be able to do it easily with the Maven Pipeline plugin.