Open in app

Sign in

Write

Sign in

Publishing a Project in Maven Central Repository

Kunal Karmakar
6 min readSep 13, 2020

--

This tutorial is for project developers who would like to promote their work by publishing their artifacts in the Maven Central Repository.

Let’s begin:

You can review steps from Maven Official Guide Page but this tutorial is a smaller version of the guide.

Firstly, make sure the following criteria are met:

  1. No project dependencies are missing in your pom.xml
  2. There are no errors in your project when you execute the mvn compile command
  3. There are no unit test failures in your project when you execute the mvn test command

Creating a Repository for your project in Maven Central Repository

Create a JIRA account: Create a JIRA account if you don’t have one from here.

Create a New Project JIRA ticket: Create a new project ticket from here. Make sure the domain you use for the group id of your project is accessible as the JIRA assignee of your ticket will ask you to verify it. Sample ticket: OSSRH-60335. Once your ticket is raised, you can wait as someone needs to be assigned to it and take action.

NOTE: Wait for the ticket to be resolved before releasing the project.

Setting up file signing through GnuPG

Install GnuPG: Install GnuPG from here if not already present in your machine. You can verify if it is already installed in your machine or not through the following command:

gpg --version

Or

gpg2 --version

If it is installed, the command will provide you with a version number.

NOTE: While setting this up, you may be asked for a passphrase, enter a new passphrase and note it down somewhere so that you do not forget it.

Setup GnuPG Keys: Now, GPG keys in your machine which will help you to sign your artifacts that you would like to upload to Maven Central. Depending on whether you have gpg or gpg2 installed, the next few commands will be of the form gpg* or gpg2*. To generate keys, execute the following command:

gpg --gen-key

Once executed, check the keys generated with the following command:

gpg --list-keys

The keys will be listed in the following format:

/home/juven/.gnupg/pubring.gpg
------------------------------
pub   1024D/C6EED57A 2010-01-13
uid                  Juven Xu (Juven Xu works at Sonatype) <juven@sonatype.com>
sub   2048g/D704745C 2010-01-13

Now, you need to distribute your generated public key to the keyserver. You can use the following command and the first key that was shown in the previous command:

gpg --keyserver hkp://pool.sks-keyservers.net --send-keys C6EED57A

To verify whether it was been sent without errors, execute the following command to receive the key:

gpg --keyserver hkp://pool.sks-keyservers.net --recv-keys C6EED57A

NOTE: At the time of publishing your artifact, if you get an error saying that the key is not found in some ‘X’ server, execute the send-keys command again to the mentioned server.

Now, it is time to set up your pom.xml so that it can communicate and upload your artifacts to the Maven Central Repository.

Setting up your pom.xml

Ensure all project-related metadata are provided in your pom.xml: The pom.xml firstly needs the groupId, artifactId, and version. Make sure that the groupId and the artifactId are the same as that in the JIRA ticket you created.

<groupId>com.github.kunalk16</groupId>    <artifactId>lightExcelReader</artifactId>    <version>1.0.1</version>

Also, provide some details about your project. These details will be displayed in Maven Central once the release is done.

<name>Light Excel Reader</name>
<description>A lightweight Java framework to read .xlsx excel files.</description>
<url>https://github.com/kunalk16/lightExcelReader</url>

Add license information: Add the license information to your pom.xml. Sample MIT license can be represented in the following way:

<licenses>
    <license>
        <name>MIT License</name>
        <url>http://www.opensource.org/licenses/mit-license.php</url>
    </license>
</licenses>

Other licenses can also be added. More information can be found here.

Add developer information: Developer information needs to be added to your pom.xml. Sample:

<developers>
    <developer>
        <name>Kunal Karmakar</name>
        <email>your_email@gmail.com</email>
        <organization>com.github.kunalk16</organization>
    <organizationUrl>https://www.github.com/kunalk16/lightExcelReader</organizationUrl>
    </developer>
</developers>

Add SCM information: The details of the repository for the source code needs to be added. For GitHub, the following format can be used:

<scm>
    <connection>scm:git:git://github.com/kunalk16/lightExcelReader.git</connection>
    <developerConnection>scm:git:ssh://github.com:kunalk16/lightExcelReader.git</developerConnection>
    <url>https://www.github.com/kunalk16/lightExcelReader</url>
</scm>

For other repositories, details can be found here.

Add distribution management details: The following format can be used:

<distributionManagement>
    <snapshotRepository>
        <id>ossrh</id>
        <url>https://oss.sonatype.org/content/repositories/snapshots</url>
    </snapshotRepository>
    <repository>
        <id>ossrh</id>
        <url>https://oss.sonatype.org/service/local/staging/deploy/maven2/</url>
    </repository>
</distributionManagement>

Add deployment and release plugins: All the following plugins are required for the deployment and release into Maven Central Repository:

<build>
    <plugins>
        <plugin>
            <groupId>org.sonatype.plugins</groupId>
            <artifactId>nexus-staging-maven-plugin</artifactId>
            <version>1.6.7</version>
            <extensions>true</extensions>
            <configuration>
                <serverId>ossrh</serverId>
                <nexusUrl>https://oss.sonatype.org/</nexusUrl>
                <autoReleaseAfterClose>true</autoReleaseAfterClose>
            </configuration>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-source-plugin</artifactId>
            <version>2.2.1</version>
            <executions>
                <execution>
                    <id>attach-sources</id>
                    <goals>
                        <goal>jar-no-fork</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>2.9.1</version>
            <executions>
                <execution>
                    <id>attach-javadocs</id>
                    <goals>
                        <goal>jar</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-gpg-plugin</artifactId>
            <version>1.5</version>
            <executions>
                <execution>
                    <id>sign-artifacts</id>
                    <phase>verify</phase>
                    <goals>
                        <goal>sign</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Your complete pom.xml should look somewhat like this:

<?xml version="1.0" encoding="UTF-8"?><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion><groupId>com.github.kunalk16</groupId>
    <artifactId>lightExcelReader</artifactId>
    <version>1.0.1</version><name>Light Excel Reader</name>
    <description>A lightweight Java framework to read .xlsx excel files.</description>
    <url>https://github.com/kunalk16/lightExcelReader</url><licenses>
        <license>
            <name>MIT License</name>
            <url>http://www.opensource.org/licenses/mit-license.php</url>
        </license>
    </licenses><distributionManagement>
        <snapshotRepository>
            <id>ossrh</id>
            <url>https://oss.sonatype.org/content/repositories/snapshots</url>
        </snapshotRepository>
        <repository>
            <id>ossrh</id>
            <url>https://oss.sonatype.org/service/local/staging/deploy/maven2/</url>
        </repository>
    </distributionManagement><developers>
        <developer>
            <name>Kunal Karmakar</name>
            <email>your_email@gmail.com</email>
            <organization>com.github.kunalk16</organization>
            <organizationUrl>https://www.github.com/kunalk16/lightExcelReader</organizationUrl>
        </developer>
    </developers><scm>
        <connection>scm:git:git://github.com/kunalk16/lightExcelReader.git</connection>
        <developerConnection>scm:git:ssh://github.com:kunalk16/lightExcelReader.git</developerConnection>
        <url>https://www.github.com/kunalk16/lightExcelReader</url>
    </scm><properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
    </properties><dependencies>
        <!-- your project dependencies here -->
    </dependencies><build>
        <plugins>
            <plugin>
                <groupId>org.sonatype.plugins</groupId>
                <artifactId>nexus-staging-maven-plugin</artifactId>
                <version>1.6.7</version>
                <extensions>true</extensions>
                <configuration>
                    <serverId>ossrh</serverId>
                    <nexusUrl>https://oss.sonatype.org/</nexusUrl>
                    <autoReleaseAfterClose>true</autoReleaseAfterClose>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-source-plugin</artifactId>
                <version>2.2.1</version>
                <executions>
                    <execution>
                        <id>attach-sources</id>
                        <goals>
                            <goal>jar-no-fork</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-javadoc-plugin</artifactId>
                <version>2.9.1</version>
                <executions>
                    <execution>
                        <id>attach-javadocs</id>
                        <goals>
                            <goal>jar</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-gpg-plugin</artifactId>
                <version>1.5</version>
                <executions>
                    <execution>
                        <id>sign-artifacts</id>
                        <phase>verify</phase>
                        <goals>
                            <goal>sign</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
            <!-- Any other plugins that your need here -->
        </plugins>
    </build>
</project>

Setting up your settings.xml:

Look out for maven’s .m2 folder if you have an existing settings.xml file. Create one if is not present.

Add JIRA credentials: JIRA credentials need to be added to your settings.xml file in the following format.

<servers>
    <server>
        <id>ossrh</id>
        <username>your-jira-id</username>
        <password>your-jira-pwd</password>
    </server>
</servers>

Add GPG passphrase to your settings.xml: Add your passphrase from the GPG setup step to your settings.xml file. This is required for signing your artifacts during upload. Sample:

<profiles>
    <profile>
        <id>ossrh</id>
        <activation>
            <activeByDefault>true</activeByDefault>
        </activation>
        <properties>
            <gpg.executable>gpg</gpg.executable>
            <gpg.passphrase>the_pass_phrase</gpg.passphrase>
        </properties>
    </profile>
</profiles>

The completed settings.xml file should look somewhat like this:

<?xml version="1.0" encoding="UTF-8"?>
<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 http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <servers>
        <server>
            <id>ossrh</id>
            <username>your-jira-id</username>
            <password>your-jira-pwd</password>
        </server>
    </servers>
    <profiles>
        <profile>
            <id>ossrh</id>
            <activation>
                <activeByDefault>true</activeByDefault>
            </activation>
            <properties>
                <gpg.executable>gpg</gpg.executable>
                <gpg.passphrase>the_pass_phrase</gpg.passphrase>
            </properties>
        </profile>
    </profiles>
</settings>

Releasing your project in Maven Central Repository:

Once you have completed your setup for GnuPG, pom.xml, and settings.xml, ensure that all the details provided are correct.

Snapshot Deployment:

Now, change your project version to something like this:

<version>1.0-SNAPSHOT</version>

This is required because we will first try a snapshot deployment of your project. After the version is modified, run the following:

mvn clean deploy

The successful execution of this command will show your project here.

Release Deployment:

Execute the following command to modify the version of your project to the required release version:

mvn versions:set -DnewVersion=1.0.0

Now, release the project using the following command:

mvn clean deploy -P release

Successful execution should upload your project artifacts in Maven Central Repository. You can then search for your repository here. After some hours, it will even be available in the Maven Repository site.

NOTE: If release deploy command execution was successful and your repository does not come up in the search, wait for some time. It may take some hours to reflect but it will do so provided your command was successfully executed.

If you face any issues, you can search with the error message in google, there will be someone who has faced your issue along with a StackOverflow post or an issue in JIRA itself.

On successful completion, your project should come up in Maven Central Repository like this. It should also show up in the Maven Repository site like this.

Do not forget to place your Maven Central Badge in your source code repository’s README.md file like this!!! ✌️

Maven
Maven Central
Open Source
Maven Repository
Maven Release Plugin

--

--

Kunal Karmakar

Written by Kunal Karmakar

8 Followers

Enthusiastic Software Engineer

Help

Status

About

Careers

Press

Blog

Privacy

Terms

Text to speech

Teams