# Nexus Repository Maven Plugin

You can use the Nexus Repository Maven plugin for deploying, moving, and deleting packages as part of Nexus Repository's [staging](https://help.sonatype.com/en/staging.html "Staging") functionality. To use this plugin, you will need to modify your project build configuration as described in this section.

The Nexus Repository Maven Plugin is available on [Maven Central Repository](https://central.sonatype.com/artifact/org.sonatype.plugins/nxrm3-maven-plugin/1.0.13/versions).

**Java Compatibility**

Versions of the Nexus Repository Maven plugin up to **1.0.7** support **Java 8**. Starting with version **1.0.11**, the plugin requires **Java 17** or higher to run within Maven.

## Configuration

The Nexus Repository Maven plugin replaces the Maven Deploy plugin in your build configuration and specifically enables staging actions for Nexus Repository 3.

You can configure the plugin by adding it to the project build plugins section of your project's `pom.xml` file as an extension:

```
<plugin>
  <groupId>org.sonatype.plugins</groupId>
  <artifactId>nxrm3-maven-plugin</artifactId>
  <!-- replace plugin version with the latest available -->
  <!-- https://search.maven.org/search?q=a:nxrm3-maven-plugin -->
  <version>1.0.3</version>
  <extensions>true</extensions>
  <configuration>
    <nexusUrl>http://localhost:8081</nexusUrl>

<!-- The server "id" element from settings to use authentication from settings.xml-->
    <serverId>local-nexus</serverId>

<!-- Which repository to deploy to -->
    <repository>maven-releases</repository>

<!-- Skip the staging deploy mojo -->
    <skipNexusStagingDeployMojo>true</skipNexusStagingDeployMojo>
  </configuration>
</plugin>
```

### Parameters

The Nexus Repository Maven plugin requires the following minimal configurations parameters:

- **serverId** \- The `id` of the `server` element in `settings.xml` from which the user credentials for accessing the repository manager should be retrieved.

- **nexusUrl** \- The base URL at which the repository manager to be used for staging is available.

- **repository** \- The name of the repository to which the plugin is to deploy.

### Maven Configurations

To successfully deploy to your repository manager, you will need to update your `~/.m2/settings.xml` file with the credentials for the deploying user. To add these credentials, add the following element to the servers element in your `~/.m2/settings.xml` file as shown below:

```
<settings>
  ...
  <servers>
    ...
    <server>
      <id>local-nexus</id>
      <username>admin</username>
      <password>admin123</password>
    </server>
  </servers>
  ...
</settings>
```

Note that the server identifier listed in Maven settings should match the `serverId` parameter you are passing to the Nexus Repository Maven plugin. In the example above, it contains the credentials for the default admin user. You should change this `username` and `password` to match your repository manager.

If you would like more control over when to activate the plugin's deploy goal, you have to explicitly deactivate the Maven Deploy plugin and replace the Maven Deploy plugin invocation with the NXRM3 Maven plugin shown in the example below:

```
<executions>
  <execution>
    <id>default-deploy</id>
    <phase>deploy</phase>
    <goals>
      <goal>deploy</goal>
    </goals>
  </execution>
</executions>
```

## nxrm3:staging-deploy

Deploying packages using the plugin relies on assigning a tag. A tag can be generated by the plugin, assigned in the project's `pom.xml`, or assigned from the command line.

**Note**

**staging.properties**

When a package is sent to staging, a `staging.properties` file is created under `./target/nexus-staging/staging` for tracking purposes. The file's contents include the name of the plugin, the date the package was staged, and the tag the package was given when staged.

You can also use this file if you accidentally staged something to perform a rollback by doing a `nxrm3:staging-delete` without a tag defined. The tag will be drawn from this file. See nxrm3:staging-delete for more about staging-delete.

Similarly, this file will be used to define the tag when you perform a staging-move without a defined tag. If you do not specify a tag in your move command, the plugin will use the last tag deployed.

### Parameters

- **tag** \- The name of the tag to be assigned to all deployed packages.

If you do not specify a tag, one will be generated automatically in the following format:

`<artifactId>-<version>-<timestamp>`

For example: `myproject-1.0.0-1554988263`

### Example Deploy

To deploy packages to Nexus Repository and assign a tag name `build-123`, you would enter the following from the command line:

```
mvn install nxrm3:staging-deploy -Dtag=build-123
```

To specify the tag in the `pom.xml` file, use the following:

```
<plugin>
    ...
    <configuration>
      ...
      <tag>build-123</tag>
       ...
```

## nxrm3:staging-move

Your Continuous Integration requirements may involve promoting packages. For example, this could involve moving packages from a testing repository to a production repository. The Nexus Repository Maven plugin provides this functionality.

### Parameters

The required parameters for a staging move operation are as follows:

- **tag** \- name of the tag to move.

- **sourceRepository** \- the source repository from which to move packages.

- **destinationRepository** \- the destination repository to which to move packages.

As with the `deploy` action tag, you can assign the `sourceRepository` and `destinationRepository` in the project's `pom.xml` or from the command line.

Below is an example of using the plugin to move all packages deployed using the tag `build-123` from the `maven-releases` repository to the `maven-production` repository.

```
mvn nxrm3:staging-move -Dtag=build-123 -DsourceRepository=maven-releases -DdestinationRepository=maven-production
```

## nxrm3:staging-delete

You can also use the Nexus Repository Maven plugin to delete deployed packages. For example, if a deployment fails part-way through, requiring a rollback, you can use the plugin to delete any currently deployed packages by tag.

**Warning**

The delete operation will delete packages associated with the given tag across all repositories and all formats.

### Parameters

- **tag** \- Delete packages associated with the given tag name.

**Note**

If you do not specify a tag, the plugin will default to using the last tag name that you used for a deploy operation.

Below is an example that will delete all packages associated with the tag `build-123`.

```
mvn nxrm3:staging-delete -Dtag=build-123
```

## Customizing Tag Value Format

If you do not prefer the default tag format of `${project.artifactId}-${project.version}-${timestamp}`, you can build it dynamically instead using a consistent format in POM configuration.

For example, in the [POM <properties> section](https://maven.apache.org/pom.html#Properties), define the [Maven build time stamp format](http://maven.apache.org/guides/introduction/introduction-to-the-pom.html#Available_Variables) you want:

```
<!--
Build timestamp.
-->
<maven.build.timestamp.format>yyyyMMddHHmm</maven.build.timestamp.format>
```

Define a POM property that defines the complete format of the staging tag name to keep it consistent for all projects:

Perhaps [re-use the project name from the pom](https://maven.apache.org/pom.html#Quick_Overview) as well:

```
<name>staging-test</name>
```

Then, define the tag name in a consistent manner in the project POM or global parent POM plugin configuration.

```
    <plugin>
      <groupId>org.sonatype.plugins</groupId>
      <artifactId>nxrm3-maven-plugin</artifactId>
      <version>1.0.2</version>
      <extensions>true</extensions>
      <executions>
        <execution>
          <id>default-deploy</id>
          <phase>deploy</phase>
          <goals>
            <goal>deploy</goal>
          </goals>
        </execution>
      </executions>
      <configuration>
        <nexusUrl>${nexusUrl}</nexusUrl>
        <tag>${nxrm3.staging.tag}</tag>
      </configuration>
    </plugin>
```

## Nexus Repository 2 Users

This plugin is distinct from the [Nexus Staging Maven Plugin](https://github.com/sonatype/nexus-maven-plugins/tree/master/staging/maven-plugin), which only enables staging actions in Nexus Repository 2. Due to underlying architectural differences of staging between Nexus Repository 2 and Nexus Repository 3, there is no backward compatibility.