Server Aliases

Since Maven 3.10.0 and 4.0.0-rc-6 (settings model 1.3.0), a server can declare a list of aliases. This is useful when the same credentials should be used for several repositories or mirrors with different IDs, without copying the whole server element.

<settings xmlns="http://maven.apache.org/SETTINGS/1.3.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.3.0 https://maven.apache.org/xsd/settings-1.3.0.xsd">
  ...
  <servers>
    <server>
      <id>company-releases</id>
      <username>my_login</username>
      <password>my_password</password>
      <aliases>
        <alias>company-snapshots</alias>
        <alias>company-mirror</alias>
      </aliases>
    </server>
  </servers>
  ...
</settings>

• aliases: For each alias, Maven creates an additional server entry with the same configuration as the original one, but with the id replaced by the alias and with an empty aliases list. In the example above, the servers company-releases, company-snapshots and company-mirror are available at runtime, all use the same credentials.

The additional servers are created in memory when the effective settings are built, so they are visible to Maven and plugins like any other server declared in settings.xml: you can see them with mvn help:effective-settings.

An alias must not be empty, and it should be unique across all server IDs and aliases. Otherwise Maven reports a warning.

Server Repository Origins

Since Maven 3.10.0 and 4.0.0, the credentials of a server are bound to the origins (scheme, host and port) of the repositories and mirrors declared with the same ID in settings.xml.

When Maven starts, it takes into account only the repositories from settings.xml profiles listed in <activeProfiles> and mirrors. Repositories from other profiles, and repositories declared in a pom.xml (in repositories, pluginRepositories or distributionManagement), are not known at that time. For such a repository, Maven reports a warning, or refuses the credentials when maven.repository.credentialScope=strict is set.

The binding protects your credentials: before, Maven matched credentials only by server ID, so any pom.xml, including the POM of a dependency or a parent, could declare a repository with the same ID pointing to another host and receive your username and password. Now, once Maven knows the hosts of a server ID, its credentials are sent only to them, and repositoryOrigins lets you add the hosts Maven cannot find by itself.

For such repositories, a server (settings model 1.3.0) can declare a list of repositoryOrigins its credentials may be used with:

<settings xmlns="http://maven.apache.org/SETTINGS/1.3.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.3.0 https://maven.apache.org/xsd/settings-1.3.0.xsd">
  ...
  <servers>
    <server>
      <id>company-releases</id>
      <username>my_login</username>
      <password>my_password</password>
      <repositoryOrigins>
        <repositoryOrigin>https://repo.example.com</repositoryOrigin>
        <repositoryOrigin>https://mirror.example.com:8443</repositoryOrigin>
      </repositoryOrigins>
    </server>
  </servers>
  ...
</settings>

• repositoryOrigins: Each repositoryOrigin is written as scheme://host or scheme://host:port. It is an origin, not a full repository URL. If a path, query or fragment is given, Maven reports a warning and ignores it. A value without a scheme or host, or with user information, is reported as an error. The comparison is case-insensitive, and the default ports 80 (http) and 443 (https) are the same as no port.

The declared origins are added to the origins Maven finds from repositories and mirrors. Nothing is replaced, so existing configurations keep working. Servers created from aliases get the same repositoryOrigins.

When a server has at least one origin, from repositories, mirrors or repositoryOrigins, its credentials are not sent to a repository with the same ID at another origin.

The binding is controlled by the maven.repository.credentialScope user property:

For Maven 4, repositoryOrigins in project settings (.mvn/settings.xml) are ignored with a warning, like credentials are, so a project cannot widen the set of hosts your credentials are sent to.

Note: The binding applies only to credentials used by Maven Resolver, for example when artifacts are downloaded or deployed with the Maven Deploy Plugin. Plugins that read a server from settings.xml directly, for example the Maven Release Plugin for SCM credentials, are not affected by it.

Password Encryption

Since Maven 2.1.0, server password and passphrase encryption is available and strongly encouraged: See details on Guide to Password Encryption.

Activation

Activations are the key of a profile. Like the POM's profiles, the power of a profile comes from its ability to modify some values only under certain circumstances; those circumstances are specified via an activation element.

<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0">
  <!-- ... -->
  <profiles>
    <profile>
      <id>test</id>
      <activation>
        <activeByDefault>false</activeByDefault>
        <jdk>21</jdk>
        <os>
          <name>Windows 10</name>
          <family>Windows</family>
          <arch>amd64</arch>
          <version>10.0.19045.5247</version>
        </os>
        <property>
          <name>mavenVersion</name>
          <value>3.9.9</value>
        </property>
        <file>
          <exists>${project.basedir}/file2.properties</exists>
          <missing>${project.basedir}/file1.properties</missing>
        </file>
      </activation>
      <!-- ... -->
    </profile>
  </profiles>
  <!-- ... -->
</settings>

Activation occurs when all specified criteria have been met, though not all are required at once.

• jdk: activation has a built in, Java-centric check in the jdk element. This will activate if the test is run under a jdk version number that matches the prefix given. In the above example, 21.0.1 will match. Ranges are also supported. See the maven-enforcer-plugin for more details about supported ranges.
• os: The os element can define some operating system specific properties shown above. See the maven-enforcer-plugin for more details about OS values.
• property: The profile will activate if Maven detects a property (a value which can be dereferenced within the POM by ${name}) of the corresponding name=value pair.
• file: Finally, a given filename may activate the profile by the existence of a file, or if it is missing.

The activation element is not the only way that a profile may be activated. The settings.xml file's activeProfile element may contain the profile's id. They may also be activated explicitly through the command line via a comma separated list after the -P flag (e.g. -P test).

To see which profile will activate in a certain build, use the maven-help-plugin.

    mvn help:active-profiles

Properties

Maven properties are value placeholder, like properties in Ant. Their values are accessible anywhere within a POM by using the notation ${X}, where X is the property. They come in five different styles, all accessible from the settings.xml file:

1. env.X: Prefixing a variable with “env.” will return the shell's environment variable. For example, ${env.PATH} contains the $path environment variable (%PATH% in Windows).
2. project.x: A dot (.) notated path in the POM will contain the corresponding element's value. For example: <project><version>1.0</version></project> is accessible via ${project.version}.
3. settings.x: A dot (.) notated path in the settings.xml will contain the corresponding element's value. For example: <settings><offline>false</offline></settings> is accessible via ${settings.offline}.
4. Java System Properties: All properties accessible via java.lang.System.getProperties() are available as POM properties, such as ${java.home}.
5. x: Set within a <properties /> element or an external files, the value may be used as ${someVar}.

<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0">
  ...
  <profiles>
    <profile>
      ...
      <properties>
        <user.install>${user.home}/our-project</user.install>
      </properties>
      ...
    </profile>
  </profiles>
  ...
</settings>

The property ${user.install} is accessible from a POM if this profile is active.

Repositories

Repositories are remote collections of projects from which Maven uses to populate the local repository of the build system. It is from this local repository that Maven calls it plugins and dependencies. Different remote repositories may contain different projects, and under the active profile they may be searched for a matching release or snapshot artifact.

<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0">
  ...
  <profiles>
    <profile>
      ...
      <repositories>
        <repository>
          <id>Snapshots</id>
          <name>Snapshots</name>
          <releases>
            <enabled>false</enabled>
            <updatePolicy>always</updatePolicy>
            <checksumPolicy>warn</checksumPolicy>
          </releases>
          <snapshots>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
            <checksumPolicy>fail</checksumPolicy>
          </snapshots>
          <url>https://oss.sonatype.org/content/repositories/snapshots</url>
          <layout>default</layout>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>myPluginRepo</id>
          <name>My Plugins repo</name>
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>false</enabled>
          </snapshots>
          <url>https://maven-central-eu....com/maven2/</url>
        </pluginRepository>
      </pluginRepositories>
      ...
    </profile>
  </profiles>
  ...
</settings>

• releases, snapshots: These are the policies for each type of artifact, Release or snapshot. With these two sets, a POM has the power to alter the policies for each type independent of the other within a single repository. For example, one may decide to enable only snapshot downloads, possibly for development purposes.
• enabled: true or false for whether this repository is enabled for the respective type (releases or snapshots).
• updatePolicy: This element specifies how often updates should attempt to occur. Maven will compare the local POM's timestamp (stored in a repository's maven-metadata file) to the remote. The choices are: always, daily (default), interval:X (where X is an integer in minutes) or never.
• checksumPolicy: When Maven deploys files to the repository, it also deploys corresponding checksum files. Your options are to ignore, fail, or warn on missing or incorrect checksums.
• layout: In the above description of repositories, it was mentioned that they all follow a common layout. This is mostly correct. Maven 2 has a default layout for its repositories; however, Maven 1.x had a different layout. Use this element to specify which if it is default or legacy.

Plugin Repositories

Repositories are home to two major types of artifacts. The first are artifacts that are used as dependencies of other artifacts. These are the majority of artifacts that reside within central. The other type of artifact is plugins. Maven plugins are themselves a special type of artifact. Because of this, plugin repositories may be separated from other repositories (although, I have yet to hear a convincing argument for doing so). In any case, the structure of the pluginRepositories element block is similar to the repositories element. The pluginRepository elements each specify a remote location of where Maven can find new plugins.