To main content
Featured image of You might already have a Maven repository

You might already have a Maven repository

Published by Benjamin Marwell on

About Apache Maven-Layout Repositories

So, what is a Maven repository? Simplified, it is a generic web server with two additional features:

  • It serves files in a specific layout (the "Maven layout")

  • Metadata files are generated and served

Examples for hosted and managed files are:

  • The artifacts themselves, using a specific naming scheme:

    • Default: groupId/artifactId/version/artifactId-version.jar

    • Additional artifacts with classifier: groupId/artifactId/version/artifactId-version-classifier.jar

  • pom.xml files, which contain the Maven coordinates of the file, dependencies, and other information.

  • .asc files, which contain the GPG signature of the artifacts and pom.xml file.

  • .md5, .sha1, .sha256, .sha512 checksum files for all the above.

  • Each parent directory also hosts a maven-metadata.xml file (plus checksums), which helps clients to find available versions.

So, that is it, simply speaking. It does a little more, which might not be relevant for you at this point. This article will not talk about access and permission grants, group IDs, or other advanced topics.

Using a web server as a Maven repository

Generally, this is a bad idea. At some point, this will be slow. You would need to implement a lot of the above features yourself, including checks for the checksum files, the metadata files, and the layout.

So, I do not recommend doing this yourself.

Using a Repository Manager as your Maven repository

There are many Maven Repository Managers available, including:

A more up-to-date list is maintained on the Apache Maven website: Apache Maven — Best Practice — Using a Repository Manager.

Using your Git Repository Manager as your Maven repository

If you checked the Apache Maven link from the previous paragraph, you might have noticed that "Gitea" is listed. You might have heard of Gitea being a Git Repository Manager. But also a Maven Repository Manager? Yes, it is. And so are many Git Repository Managers.

And so on. So, if you are using a Git Repository Manager, you already have a Maven repository. Now, I cannot get into the details of every Git Repository Manager. But here are the links to the manuals you are probably looking for:

Using GitHub (public or on-premise) as a Maven repository

The GitHub documentation about using GitHub as a Maven Repository Manager is very exhaustive. It is called: GitHub — Working with the Apache Maven registry.

Using GitLab (public or on-premise) as a Maven repository

GitLab has similar documentation. It is called: GitLab — Maven packages in the package registry.

Using Gitea (free / oss) as a Maven repository

Gitea hosts documentation with many examples which are straightforward to follow. You can find it for version 1.23.7 as Gitea — Maven Package Registry.

Using codeberg.org for hosting Maven Artifacts in a Maven repository

If you are hosting your projects on codeberg.org, you might be wondering if you can use it as a Maven repository. Yes, they do support it: Codeberg — Publish Maven packages for your user or organization

How to upload your Non-Maven artifacts

If you want to upload non-Maven artifacts, you can use Apache Maven with the maven-deploy-plugin. The goal you want to use is called deploy-file.

Beware that all metadata must be supplied on the command line. So this call can get very long:

Uploading a file to a Maven repository
mvn deploy:deploy-file \
  -DgroupId=com.example \
  -DartifactId=example-artifact \
  -Dversion=1.0.0 \
  -Dpackaging=zip \
  -Dfile=/path/to/file.zip \
  -DrepositoryId=my-repo \
  -Durl=https://my.repo.com/repository/

With additional files, types and classifiers, or JavaDoc, this command can even get longer.

Uploading signatures after uploading

I haven’t tried this on GitHub packages, but it works on Nexus 3 and Artifactory. You can actually sign the files afterwards and upload the signatures afterwards. We can use the maven-gpg-plugin for this. The goal is called gpg:sign-deployed.

Uploading signatures to a Maven repository after the artifacts were already deployed
mvn gpg:sign-deployed \
  -Dgpg.bestPractices=true \
  -DrepositoryId=my-repo \
  -Durl=https://my.repo.com/repository/

Signing the artifacts before uploading

You can also do this in one go if you want to. If you want to upload abirtrary files to a Maven Repository, this is probably the command you want to use. Again we use the maven-gpg-plugin for this. The goal is called sign-and-deploy-file.

mvn gpg:sign-and-deploy-file \
  -Dgpg.bestPractices=true \
  -DgroupId=com.example \
  -DartifactId=example-artifact \
  -Dversion=1.0.0 \
  -Dpackaging=zip \
  -Dfile=/path/to/file.zip \
  -DrepositoryId=my-repo \
  -Durl=https://my.repo.com/repository/

Again, this gets more complicated with additional files, types and classifiers, or JavaDocs.

Adding additional checksums

Maven defaults to MD5 and SHA1 checksums before Version 4.0.0. This is fine for most cases to detect bitrot, but not for security. For security, you should always use detached signatures as described above.

However, if your policy requires SHA256 or SHA512 checksums, you can add them while uploading using a system property:

You cannot remove the default checksums. Without MD5 and SHA1, the upload will most likely fail. Even if this works, most clients will fail as they expect those files to be present.
Uploading with additional checksums to a Maven repository
mvn {your-goal} \
  -Daether.layout.maven2.checksumAlgorithms=MD5,SHA-1,SHA-256,SHA-512 \
  {other options}

Using JReleaser to upload artifacts

If you need staging or a more advanced upload mechanism, take a look at JReleaser. They have a whole guide on how to upload artifacts to Maven Central or a custom repository (JReleaser).

Conclusion

If you are using a Git Repository Manager already, you might already have a Maven repository. There is no need to set up a dedicated Maven Repository Manager unless you need more advanced features. You can go with the Git Repository Manager you already have if you only need file hosting.

But then you need a full-fledged Maven Repository Manager if you need more advanced features, like:

  • Clients should not need to set up a lot of repositories.

  • Advanced permissions and access control are needed.

  • Mirror functionality for artifacts from a remote repository.

  • An integrated security scanner for your artifacts is needed.
    While some Repository Managers have this feature (like GitHub with Dependabot), it is not available in all of them.

So, what do you use? Let me know in the comments!