Maven Repository

Maven is a build automation tool primarily associated with the Java programming language. Developed by the Apache Software Foundation and released in 2004 it provides a standardized way to describe how a software project is built.

A Maven Repository or Maven Repo is a registry of packaged files, stored, indexed, and made accessible to projects that depend on them. Each package has a unique name and version allowing for repeatable continuous integration and continuous delivery (or continuous deployment) tasks.

The Maven repository index stores metadata about each package; that the Maven tooling looks up at build time enabling pulling in of dependency projects and extensions.

For more information on Maven, please see:

• Maven: The official website for Apache Maven
• Maven Central: Popular public repository for Maven artifacts

If using Gradle - please see our Gradle documentation
If using sbt - please see our sbt documentation

Contextual Documentation

The examples in this document are generic. Cloudsmith provides contextual setup instructions within each repository, complete with copy n' paste snippets (with your namespace/repo/rsa-key pre-configured).

In the following examples:

Upload a Package

To upload, you need to generate your package first. You can do this with:

mvn package

This generates a Maven package file (.jar or similar) like your-package-1.2.3.jar that you can upload.

📘

You will always need at least the package file and the POM file for uploading.

What is a POM?

A POM, the Project Object Model, is the XML file that describes all the aspects of your project that relate to building and packaging the source code into a package file. Typically a jar (java archive). The metadata held within the pom.xml that is typically stored within the jar itself allows Maven to index the package into a Maven Repository for easy distribution.

What is a Fat Jar?

A Fat Jar, is also referred to as an Uber Jar, is a Java Archive library that contains all classes, including all the classes of its dependencies. This allows the Jar to be run standalone without requiring any further code available on the Class Path.

The disadvantage of creating an all-in-one jar mean that you have to deploy everything (a potentially large file) each time. If you split the Fat Jar into components you can separately test, version and release code enabling faster deployments and your developers to cherry-pick components for inclusion in other projects.

Upload via Maven

The endpoint for the native Maven API is:

https://maven.cloudsmith.io/OWNER/REPOSITORY/

The distribution repositories define where to push your artifacts. In this case it will be a single repository, but you can configure alternatives. Add the following to your project pom.xml file:

<distributionManagement>
  <snapshotRepository>
    <id>NAME</id>
    <url>https://maven.cloudsmith.io/OWNER/REPOSITORY/</url>
  </snapshotRepository>
  <repository>
    <id>NAME</id>
    <url>https://maven.cloudsmith.io/OWNER/REPOSITORY/</url>
  </repository>
</distributionManagement>

📘

You can configure different repositories for snapshots and releases, and you can replace NAME with your own identifier(s) (but make sure they match settings elsewhere).

You then can configure your ~/.m2/settings.xml file with the API key of the uploading user:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      https://maven.apache.org/xsd/settings-1.0.0.xsd">
  <servers>
    <server>
      <id>NAME</id>
      <username>USERNAME</username>
      <password>API-KEY</password>
    </server>
  </servers>
</settings>

You can now publish to the native API with:

mvn deploy

📘

You can find out more about Maven publishing in the official Maven documentation.

Upload via the Cloudsmith CLI

The command to upload a Maven package via the Cloudsmith CLI is:

cloudsmith push maven OWNER/REPOSITORY ARTIFACT_ID-PACKAGE_VERSION.jar --pom-file=ARTIFACT_ID-PACKAGE_VERSION.pom

Example:

cloudsmith push maven org/repo validation-api-1.0.0.GA.jar --pom-file=validation-api-1.0.0.GA.pom

Upload via Cloudsmith Website

Please see Upload a Package for details of how to upload via the Website UI.

Example Project

For examples of what your project should look like for packaging and publishing/uploading, please have a look at our examples repository (on GitHub). We'll supplement these with more detailed guidance later, but otherwise just ask, we're here to help!

Download / Install a Package

Setup

To enable the retrieval of Cloudsmith hosted packages via Maven, the first step is to add your repository to the dependencyManagement section of your pom.xml file.

To do this add one of the following XML examples to your project pom.xml file:

Public Repositories

<repositories>
  <repository>
    <id>NAME</id>
    <url>https://dl.cloudsmith.io/public/OWNER/REPOSITORY/maven/</url>
    <releases>
      <enabled>true</enabled>
      <updatePolicy>always</updatePolicy>
    </releases>
    <snapshots>
      <enabled>true</enabled>
      <updatePolicy>always</updatePolicy>
    </snapshots>
  </repository>
</repositories>

Private Repositories

📘

Private Cloudsmith repositories require authentication. You can choose between two types of authentication, Entitlement Token Authentication or HTTP Basic Authentication.

The setup method will differ depending on what authentication type you choose to use.

🚧

Entitlement Tokens, User Credentials and API-Keys should be treated as secrets, and you should ensure that you do not commit them in configurations files along with source code or expose them in any logs

<repositories>
  <repository>
    <id>NAME</id>
    <url>https://dl.cloudsmith.io/TOKEN/OWNER/REPOSITORY/maven/</url>
    <releases>
      <enabled>true</enabled>
      <updatePolicy>always</updatePolicy>
    </releases>
    <snapshots>
      <enabled>true</enabled>
      <updatePolicy>always</updatePolicy>
    </snapshots>
  </repository>
</repositories>

<repositories>
  <repository>
    <id>NAME</id>
    <url>https://dl.cloudsmith.io/basic/OWNER/REPOSITORY/maven/</url>
    <releases>
      <enabled>true</enabled>
      <updatePolicy>always</updatePolicy>
    </releases>
    <snapshots>
      <enabled>true</enabled>
      <updatePolicy>always</updatePolicy>
    </snapshots>
  </repository>
</repositories>

If using HTTP Basic Authentication, you need to provide one following three types of credentials:

• Cloudsmith Username and Password
• Cloudsmith API Key
• An Entitlement Token

When using HTTP Basic Authentication you'll probably want to keep your credentials separately in your settings.xml file instead of within the pom.xml file. once you have decided which credentials you wish to use, setup your settings.xml file as follows:

<settings>
  <servers>
    <server>
      <id>NAME</id>
      <username>USERNAME</username>
      <password>PASSWORD</password>
    </server>
  </servers>
</settings>

<settings>
  <servers>
    <server>
      <id>NAME</id>
      <username>USERNAME</username>
      <password>API-KEY</password>
    </server>
  </servers>
</settings>

<settings>
  <servers>
    <server>
      <id>NAME</id>
      <username>token</username>
      <password>TOKEN</password>
    </server>
  </servers>
</settings>

📘

We would highly advise that you encrypt your credentials using something like mvn encrypt-password, of which you can refer to the mini encryption guide for more detailed help (external link).

For more details on authentication in Maven, please refer to the official Maven documentation (external link).

Specifying Dependencies

After the repository is added to the pom.xml file, and credentials are added to the settings.xml file (if using HTTP Basic Authentication), all that is left is to specify the dependency in the dependencies section of the project pom.xml file.

To do this add the following XML to your project pom.xml file:

<dependency>
  <groupId>GROUP_ID</groupId>
  <artifactId>ARTIFACT_ID</artifactId>
  <version>PACKAGE_VERSION</version>
</dependency>

Install a Package

To download all the dependencies specified in your pom.xml file and build your project you just need to run:

mvn install

Security Scanning

Supported
Please see our Security Scanning documentation for further information.

Upstream Proxying / Caching

Configurable Proxying Caching
You can configure upstream Maven repositories that you wish to use for packages that are not available in your Cloudsmith repository. In addition, you can also choose to cache any requested packages for future use.

Please see our Upstream Proxying documentation for further instructions.

Key Signing Support

GPG Index Packages

Troubleshooting

Please see the Troubleshooting Maven page for further help and information.