sap-jenkins-library/documentation/architecture/decisions/nexusUpload.md

Artifact Deployment to Nexus

Status

Accepted

Context

The nexusUpload step shall upload (deploy) build artifacts to a Nexus Repository Manager. Nexus version 2 and 3 need to be supported. Per module, there can be an artifact and multiple sub-artifacts, which need to be deployed as a unit, optionally together with the project descriptor file (i.e. pom.xml or mta.yaml). A Nexus contains repositories of different type. For example, a "release" repository does not allow updating existing artifacts, while a "snapshot" repository allows for multiple builds of the same snapshot version, with the notion of a "latest" build. Depending on the type of repository, a certain directory layout has to be obeyed, and maven-metadata.xml files have to be maintained in order to be compatible with tools consuming the artifacts. The Nexus itself may also have mechanisms in place, for example to automatically purge old builds in snapshot releases. All this makes it important to make compatible deployments.

Alternatives

• Apache Maven Deploy Plugin
• Maven lifecycle phase : deploy
• Uploading artifacts manually

Pros and Cons

Apache Maven Deploy Plugin (deploy:deploy-file)

For this option, we only consider the goal deploy:deploy-file.

👍

• Official maven plugin for deployment, which is perfect if you only care whether the artifacts are deployed correctly.

👎

• Knowledge about which artifacts to deploy has to be obtained manually.
• A list of parameters has to be generated before using the plugin, including artifactId and version, which is the same case as the Uploading artifacts manually. For maven projects, the parameters can be obtained using the evaluate goal of the maven-help-plugin. There is however a performance impact, since a maven command line has to be executed for each parameter, multiplied by the number of modules. This is not a problem for Maven lifecycle phase : deploy.
• Credential info has to be stored in a settings.xml, which introduces additional implementation. Credentials can be passed via environment variables.

Maven lifecycle phase: deploy

By default, the maven lifecycle phase deploy binds to the goal deploy:deploy of the Apache Maven Deploy Plugin.

👍

• Same as the Apache Maven Deploy Plugin
• You don't have to obtain and pass the parameters as for Apache Maven Deploy Plugin, because package phase is executed implicitly and makes the parameters ready before deploy phase.
• Supports multi-module Maven projects and any project structure.

👎

• Same case as the Apache Maven Deploy Plugin for handling credentials.
• Cannot be used for non-Maven projects (i.e. MTA)
• As a maven phase, a list of phases is triggered implicitly before this phase, including compile, test and package.

To follow the build-once principle, all these phases have to be skipped. However, it's not possible to skip some of the maven goals binding to certain phases. For example, if the <packaging> tag of the pom.xml is set to jar, then the jar:jar goal of the Apache Maven JAR Plugin is bound to the package phase. Unfortunately, however, Apache Maven JAR Plugin does not provide an option to skip the the jar:jar goal. There may be a solution, but it seems to require modifying the pom and could also be different depending on the used packaging. This is the main reason why we cannot use this option.

Uploading artifacts manually

Files can be uploaded to the Nexus by simple HTTP PUT requests, using basic authentication if necessary. Meta-data files have to be downloaded, updated and re-uploaded after successful upload of the artifacts.

👍

• Without the pain of handling the credentials, which was mentioned above in Apache Maven Deploy Plugin section.
• Gives full control over the implementation.

👎

• Same as the Apache Maven Deploy Plugin. Knowledge about which artifacts to deploy has to be obtained manually.
• Same as the Apache Maven Deploy Plugin. A list of parameters has to be prepared.
• Introduces complexity for maintaining maven-metadata.xml. For example there is a great difference between "release" and "snapshot" deployments. The later have a build number and another directory structure on the nexus (arbitrary number of builds per version, with metadata for each build and for the version).
• Has the greatest maintenance-overhead.

Decision

Apache Maven Deploy Plugin is chosen, because:

• Maven lifecycle phase: deploy conflicts with the build-once principle.
• Credentials handling is not very complex to implement.
• Has the fine-grained control needed over which artifacts are deployed.
• Maintains maven-metadata.xml correctly for various types of deployments.