How to upload personal open source projects to maven central warehouse

Recently, I am writing some open source projects, and I want to put the things I wrote in the maven central repository and make them available to more people. So I wrote this article to record the entire process of successfully uploading and synchronizing the jar package of the self-developed open source project with the maven central warehouse. There are still many pits in it.
[TOC]

• First of all, you need to complete the application for a new project on the sonatype JIRA management platform, and you can upload the jar after the review is passed.
• The upload process must first be packaged locally. In order to maintain the integrity of the project information and the security of the upload process, special operations are required, which will be described in detail later.
• After local packaging, the sonatype Nexus staging library is first imported. This library is only used for temporary storage. After verifying that the content is complete and the information is complete, it can be transferred to the release library through platform operations.
• After the open source project jar is transferred to the release library, all the content that we need to operate is actually completed. The project of the sonatype maven library will be automatically synchronized to the maven central warehouse. There will be a delay in this process, but the delay is very short.
• If you use the image of the domestic maven central warehouse, there will be a relatively large delay with the maven central warehouse. Please wait patiently for synchronization before you can use it.

1. The OSSRH account is registered in the configuration

sonatype is a community-supported open source project hosting service (Open Source Project Repository Hosting, referred to as OSSRH), which is free, and developers can host maven jar packages generated by their own open source projects here. When the maven project is packaged and deployed here, it will be automatically synchronized to the maven central repository. So no matter what, we all need to register a sonatype platform account first.

1.1. Account registration

Registration address: https://issues.sonatype.org/secure/Signup !default.jspa , fill in your email, full name, login username username, login password passwprd as shown in the figure below, and fill in the verification code. Complete the registration. Friendly reminder: The strength of the password during the registration process is very high. After filling in, it is best to find a notepad to write down the password first, and forget it when you use it later. In addition, after the registration is completed, there is no "registration successful" related prompt, but directly jumps to the login interface.

Use the user we just registered to log in. After logging in, we will be prompted to choose a language: I am used to Chinese, of course, choose Chinese; then we will be prompted to choose an avatar; then we will be prompted what work to do, "just browse the current project" , this step is not important.

After entering the JIRA management platform, click the "New" button in the top navigation bar, and then fill in the information in the pop-up modal box, as follows:

• Project and question type, be sure to select the right ones, and operate according to the picture
• Just fill in the project name for the summary content, and fill in the Group Id as needed according to the maven coordinates of the project, which is consistent with the pom configuration of the maven project. (Note here: In actual operation, first read "1.2. Domain Name Authentication" below, and then do this operation, there is a corresponding relationship to avoid mistakes)
• After the code is uploaded to GitHub, the project URL and the scm version management URL (with .git) are filled in in turn as shown in the figure.

Click New to create a new question. In fact, a review workflow for a new project review is initiated, and someone will review the information you fill in.

1.2. Domain Name Authentication

Because the Group ID I filled in above is the domain name I purchased myself, so I need to prove that this domain name is mine. The way of proof is also very simple. It is to add a txt domain name resolution record to the domain name on the platform where I purchased the domain name. The value of the domain name resolution record will be given in the process audit result record of the JIRA platform, as shown in the red box in the figure below. (The serial number of this new project application: OSSRH-83481).

What if I don't have a domain name? Without a domain name, you can fill in the github user domain for the Group Id, such as: com.github.<gihub用户名> . Fill in the github user domain, and the verification method is different. You need to create an empty warehouse in github. The name of the warehouse is OSSRH-83481 .

Because my domain name was bought on Alibaba Cloud, I went to Alibaba Cloud to add a TXT type resolution record value for the domain name.

If you are not sure whether the TXT parsing record value is effective, you can use the Windows CMD command line to respond to the following information to prove that the setting is correct

 > nslookup -type=TXT 你的域名
服务器:  dns.google
Address:  8.8.8.8

非权威应答:
你的域名       text =

        "OSSRH-83481"

After the domain name resolution record value is added, go back to the sonatype JIRA management platform. In the OSSRH-83481 question as shown in the figure below, there is a Respose button, click this button to prove that you have completed the domain name authentication operation. (Because I wrote this article after the operation was completed, this button is gone, I simulated one)

During the entire process of creating new issues and project process review, your registered mailbox will continue to receive emails from the sonatype JIRA management platform, reminding you what stage the review process has reached. (This review process is very fast. It should be a robot review, not a human operation. I completed the entire review process in 5 minutes). After the review is passed, you will see the following status: Resolved.

2. Install the GnuPG software and generate a signature

After the new project is approved, we need to install GnuPG on the development PC, because all the files we upload to the sonatype maven library must be signed by GnuPG, and files that are not signed cannot be uploaded successfully. Download address: https://gpg4win.org/thanks-for-download.html . After the download is complete, the fool-like "Next" and "Next" can be installed.
After the download is complete, we open the Windows CMD command line and execute the following command. (Note: My operations are all performed under the CMD command line, no power shell, no git bash. I have tried it all, but it is not impossible, the operation process is inconsistent. If it is inconsistent with my operation process, it may cause your operation to fail. !)

 gpg --gen-key

The red part in the picture below is what I filled in, my name, email, and an O for ok. We will be prompted to enter a Passphrase, fill in 2 times. This Passphrase is a password, you must remember it, it will be used later.

After the public key and private key pair signed by GnuPG is generated, you can use the following command to view the result

 C:\Users\hanxt>gpg --list-key
gpg: checking the trustdb
gpg: marginals needed: 3  completes needed: 1  trust model: pgp
gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
gpg: next trustdb check due at 2024-08-09
C:\Users\hanxt\AppData\Roaming\gnupg\pubring.kbx
------------------------------------------------
pub   ed25519 2022-08-10 [SC] [expires: 2024-08-09]
      6B4F6A477A1BE195326AEAFA0EE41461FB92CD0B
uid           [ultimate] HanXiaotong <[e-mail]>
sub   cv25519 2022-08-10 [E] [expires: 2024-08-09]

After the key pair is generated, send its public key to the keyserver approved by sonatype. The string of the public key can be viewed through gpg --list-key above.

 gpg --keyserver keyserver.ubuntu.com --send-keys 6B4F6A477A1BE195326AEAFA0EE41461FB92CD0B

Through the following command line, you can verify whether the string of the public key is sent to the server successfully.

 gpg --keyserver keyserver.ubuntu.com --recv-keys 6B4F6A477A1BE195326AEAFA0EE41461FB92CD0B

3. Project basic configuration

After completing the above preparations, we need to package the project. The packaging tool I use is maven. It is necessary to check whether the following information is fully configured. If not, please add it! Without this information, the maven project will not be able to transition to the release state in the future. Please fill in according to the actual situation of your project.

 <groupId>com.zimug</groupId>
<artifactId>zimug-monitor-threadpool</artifactId>
<version>1.0</version>

<name>${project.groupId}:${project.artifactId}</name>
<description>spring boot starter  for thread pool monitor  </description>
<url>https://github.com/hanxt/zimug-monitor-threadpool</url>

Fill in the open source agreement in license, fill in the git code repository address of the project in scm, and fill in the contact information of the developer in developer.

 <licenses>
    <license>
      <name>BSD 3-Clause</name>
      <url>https://spdx.org/licenses/BSD-3-Clause.html</url>
    </license>
  </licenses>
  <scm>
    <connection>https://github.com/hanxt/zimug-monitor-threadpool.git</connection>
    <url>https://github.com/hanxt/zimug-monitor-threadpool</url>
  </scm>
  <developers>
    <developer>
      <name>zimug</name>
      <email>[e-mail]</email>
      <roles>
        <role>Developer</role>
      </roles>
      <timezone>+8</timezone>
    </developer>
  </developers>

Fourth, maven packaging configuration

Only users registered on the sonatype JIRA management platform can upload open source project jars to the sonatype Nexus repository. So when we upload the jar file, it is necessary to inform the server of our registered user name and password. Find maven's setting.xml and add the following configuration:

 <servers>
    <server>
      <id>ossrh</id> 
      <username>sonatype注册username</username>
      <password>sonatype注册用户的password</password>
    </server>
</servers>

setting.xml is a global configuration for maven. In addition, pom.xml needs to be configured for the project. First, configure the address of the remote warehouse. It should be noted that the id here should be the same as the id configured by the server in setting.xml.

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

Here are a few points to note,

• snapshotRepository is the upload address of the snapshot version of the project. If the version number of the project, such as 1.0-SNAPSHOT, will be uploaded to this repository.
• Usually the repository is the upload address of the remote repository where we really need to publish the project. It should be noted that what we wrote here is the staging temporary address, not the address of the release version. (Why do this? Details later)
• In addition, it should be noted that the address of the remote warehouse we uploaded is prefixed with s01, while the older articles do not have the s01 prefix. This is because the old sonatype maven warehouse is already full of resources, so the official newly built s01 maven warehouse, and there may be s02 and s03 in the future. At this stage, users registered on the sonatype JIRA management platform can only upload this new s01 repository.

After the remote warehouse configuration is completed, we also need to add some packaging configurations to the project pom.xml. These configurations basically do not need to be modified, and can be pasted in as they are. (The maven-gpg-plugin plugin will call the GnuPG software installed above to sign the file)

 <profiles>
  <profile>
    <id>release</id>
    <build>
      <plugins>
        <!-- Source -->
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-source-plugin</artifactId>
          <version>2.2.1</version>
          <executions>
            <execution>
              <phase>package</phase>
              <goals>
                <goal>jar-no-fork</goal>
              </goals>
            </execution>
          </executions>
        </plugin>
        <!-- Javadoc -->
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-javadoc-plugin</artifactId>
          <version>2.9.1</version>
          <configuration>
            <show>private</show>
            <nohelp>true</nohelp>
            <charset>UTF-8</charset>
            <encoding>UTF-8</encoding>
            <docencoding>UTF-8</docencoding>
            <additionalparam>-Xdoclint:none</additionalparam>
            <!-- TODO 临时解决不规范的javadoc生成报错,后面要规范化后把这行去掉 -->
          </configuration>
          <executions>
            <execution>
              <phase>package</phase>
              <goals>
                <goal>jar</goal>
              </goals>
            </execution>
          </executions>
        </plugin>
        <!-- GPG -->
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-gpg-plugin</artifactId>
          <version>1.6</version>
          <executions>
            <execution>
              <phase>verify</phase>
              <goals>
                <goal>sign</goal>
              </goals>
            </execution>
          </executions>
        </plugin>
        <!--Compiler -->
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-compiler-plugin</artifactId>
          <version>3.0</version>
          <configuration>
            <source>1.8</source>
            <target>1.8</target>
            <fork>true</fork>
            <verbose>true</verbose>
            <encoding>UTF-8</encoding>
          </configuration>
        </plugin>
        <!--Release -->
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-release-plugin</artifactId>
          <version>2.5.1</version>
        </plugin>
      </plugins>
    </build>
  </profile>
</profiles>

In the project root directory, run the following command to perform maven packaging operation (and deploy the project jar to the remote maven repository). During the packaging and running process, a dialog box will pop up to prompt you to enter the passphrase, enter the above " Install the GnuPG software and generate the Passphrase you filled in in the "Signature" chapter.

 mvn clean install deploy -P release

The things to note here are:

• Do not use IDEA's maven UI packaging. IDEA's maven UI packaging will report an error and cannot execute the gpg command. As for the specific reason, I don't know the reason, just use the CMD command line above to package it.
• When packaging using the mvn command line, you need to pay attention to whether your JAVA_HOME environment variable points to the version you expect. I have multiple versions of JDK installed on my computer, JAVA_HOME points to JDK11, and the version I want to package is JDK8. May cause confusion!
• If maven depoly issues a command and reports a 401 authentication error, it is because the username and password of the server configuration in your maven setting.xml are incorrect, or the server configuration id in setting.xml is inconsistent with the repository id configured in the pom. It is also possible that there are multiple versions of maven on your computer, and the project does not use the same setting.xml.
• If a 400 error is reported, it is very likely that you have uploaded the jar, and the same version has been uploaded again and again.

5. CLOSE&RELEASE

After the project jar is correctly uploaded to the nexus repository, we need to perform further operations. This is because the jar we uploaded is put into the staging temporary repository, and we need to transfer it to the release repository, where the sonatype platform will check the integrity of your project information, jar document, source code, etc. Projects that fail the verification cannot be transferred to release, and cannot be synchronized to the maven central repository.

These operations require us to log in through the interface and use the sonatype registered user: https://s01.oss.sonatype.org/ . As shown in the figure, if our project is packaged and uploaded successfully, you will see a Repository in the Staging Repository and check it. After clicking the "CLOSE" button, the integrity check will be performed automatically, and the check result can be viewed by double-clicking the row where the warehouse is located. (As long as you fill in the project information and packaging configuration in the pom according to what I said above, it will basically pass the verification here)

After the CLOSE verification is passed, refresh the page several times, and the Release button becomes clickable. At this point, click the Release button to transfer the project jar from the Staging temporary repository to the Release official repository. In fact, all the content we need to operate is completed.

The project of the sonatype maven library will be automatically synchronized to the maven central warehouse, which can be imported and used through the maven coordinates. Don't worry, there may be some delay in this process. After uploading, it may not be searchable in the maven central warehouse for a period of time, but there is no problem in downloading the jar package using maven coordinates.

After everything is ok, it is best to go back to the sonatype JIRA management platform and close the "issue", so that the sonatype JIRA management process is all completed.

Welcome to pay attention to my announcement number: Antetokounmpo, reply 003 and present the PDF version of the author's column "The Way of Docker Cultivation", more than 30 high-quality docker articles. Antetokounmpo Blog: zimug.com