maven central repository에 라이브러리 배포하기

github의 maven project를 maven central repotisory (https://search.maven.org/)에 등록하면서 한 작업들을 기록

등록을 위한 가이드는 아래와 같다.

https://central.sonatype.org/publish/publish-guide/

OSSRH Guide - The Central Repository Documentation

등록을 위한 프로젝트 pom.xml 기본 설정

https://central.sonatype.org/publish/requirements/

Requirements - The Central Repository Documentation

0. 배포할 프로젝트가 우선 준비되어 있어야 한다.

해당 프로젝트를 기준으로 배포 요청을 하기 때문

1. 프로젝트 이름, 설명, URL을 명시해야 한다.

<name>Example Application</name>
<description>A application used as an example on how to set up pushing
  its components to the Central Repository.</description>
<url>http://www.example.com/example-application</url>

이름의 경우 Maven 속성을 사용하여 다음과 같은 형태로도 사용 가능하다.

<name>${project.groupId}:${project.artifactId}</name>

2. license 정보를 명시해야 한다.

apache license의 경우

<licenses>
  <license>
    <name>The Apache License, Version 2.0</name>
    <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
  </license>
</licenses>

MIT license의 경우

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

3. 개발자 정보를 명시해야 한다.

 <developers>
    <developer>
      <name>Manfred Moser</name>
      <email>manfred@sonatype.com</email>
      <organization>Sonatype</organization>
      <organizationUrl>http://www.sonatype.com</organizationUrl>
    </developer>
  </developers>

4. SCM 정보를 명시해야 한다.

지원되는 다양한 SCM정보는 Maven SCM Documentation에서 확인할 수 있다.

JavaDoc 및 Source 제공

대상 jar package 외에 javadoc과 source를 제공해야 한다.

다양한 예는 아래와 같다.

자체 Subversion

<scm>
  <connection>scm:svn:http://subversion.example.com/svn/project/trunk/</connection>
  <developerConnection>scm:svn:https://subversion.example.com/svn/project/trunk/</developerConnection>
  <url>http://subversion.example.com/svn/project/trunk/</url>
</scm>

Github

<scm>
  <connection>scm:git:git://github.com/simpligility/ossrh-demo.git</connection>
  <developerConnection>scm:git:ssh://github.com:simpligility/ossrh-demo.git</developerConnection>
  <url>http://github.com/simpligility/ossrh-demo/tree/master</url>
</scm>

BitBucket에서 호스팅 되는 Git

<scm>
  <connection>scm:git:git://bitbucket.org/simpligility/ossrh-pipeline-demo.git</connection>
  <developerConnection>scm:git:ssh://bitbucket.org:simpligility/ossrh-pipeline-demo.git</developerConnection>
  <url>https://bitbucket.org/simpligility/ossrh-pipeline-demo/src</url>
</scm>

BitBucket에서 호스팅 되는 Mercurial

<scm>
  <connection>scm:hg:http://bitbucket.org/juven/hg-demo</connection>
  <developerConnection>scm:hg:https://bitbucket.org/juven/hg-demo</developerConnection>
  <url>http://bitbucket.org/juven/hg-demo</url>
</scm>

Apache Maven에서 Apache Git Server의 Git

<scm>
  <connection>scm:git:https://git-wip-us.apache.org/repos/asf/maven.git</connection>
  <developerConnection>scm:git:https://git-wip-us.apache.org/repos/asf/maven.git</developerConnection>
  <url>https://github.com/apache/maven/tree/${project.scm.tag}</url>
  <tag>master</tag>
</scm>

여기까지 열거한 다양한 정보들을 정리하면 아래와 같다. (이게 전부는 아님)

<?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/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.simpligility.training</groupId>
  <artifactId>ossrh-demo</artifactId>
  <version>1.0</version>
  <packaging>jar</packaging>

  <name>ossrh-demo</name>
  <description>A demo for deployment to the Central Repository via OSSRH</description>
  <url>http://github.com/simpligility/ossrh-demo</url>

  <licenses>
    <license>
      <name>The Apache Software License, Version 2.0</name>
      <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
    </license>
  </licenses>

  <developers>
    <developer>
      <name>Manfred Moser</name>
      <email>manfred@sonatype.com</email>
      <organization>Sonatype</organization>
      <organizationUrl>http://www.sonatype.com</organizationUrl>
    </developer>
  </developers>

  <scm>
    <connection>scm:git:git://github.com/simpligility/ossrh-demo.git</connection>
    <developerConnection>scm:git:ssh://github.com:simpligility/ossrh-demo.git</developerConnection>
    <url>http://github.com/simpligility/ossrh-demo/tree/master</url>
   </scm>

...

</project>

5. 고유 groupId 사용

또한 등록을 위한 고유한 groupId를 소유해야 한다.

예를 들면 다음과 같다.

• www.springframework.org -> org.springframework
• subdomain.example.com -> example.com
• github.com/yourusername -> io.github.yourusername
• my-domain.com -> com.my-domain

Sonatype Jira 계정 생성

https://issues.sonatype.org/secure/Signup!default.jspa

업로드를 위한 계정을 생성한다.

Sonatype Jira로 새 프로젝트 업로드 권한 생성 요청

https://issues.sonatype.org/secure/CreateIssue.jspa?issuetype=21&pid=10134 

프로젝트를 repository에 업로드할 수 있도록 권한을 요청한다.

해당 jira 등록과 관련한 영상 가이드도 있다.

https://www.youtube.com/watch?v=0gyF17kWMLg 

Github 계정 소유권 확인을 위한 repository 생성

Sonatype Jira로 새 프로젝트 업로드 권한을 요청하면 해당 Jira는 OSSRH-[번호]의 형태로 Issue가 생성된다. 

이 생성된 이슈와 동일한 이름의 public repository를 내 Github에 생성하면 된다.

예를 들어 생성된 Issue가 OSSRH-71335 라면 해당 이름의 repository를 다음과 같이 생성하면 된다.

해당 프로젝트 소유권을 확인하기 위한 절차이고 해당 Jira Issue가 처리되고 나면 생성한 Repository는 삭제하면 된다.

다른 사람들의 글을 찾아보니 2일 이내 처리라고 되어 있었는데 내 경우 요청하고 5분 안에 피드백이 왔고 놓치고 있다가 3시간 만에 답변을 하니 답변도 바로 처리를 해주어서 3시간밖에 걸리지 않았다. (내 답변이 늦어서 3시간이 걸린 거고 그게 아니라면 바로 처리나 마찬가지였다.)

해당 이슈가 처리되고 나면 생성한 계정으로 https://s01.oss.sonatype.org/ 에 업로드를 할 수 있도록 권한이 주어지며 로그인을 할 수 있게 된다.

이 권한은 요청한 groupId의 프로젝트에 대한 업로드 권한이기 때문에 생성된 groupId 및 하위 group으로 생성된 프로젝트는 모두 해당 권한에 속하기 때문에 최초 1번만 요청하면 이후 얼마든지 해당 groupId 및 하위 group에 대해 다양한 artifactId를 등록할 수 있게 된다.

GPG key 생성

https://central.sonatype.org/publish/requirements/gpg/

Working with PGP Signatures - The Central Repository Documentation

maven repository에 release를 배포하기 위해서는 pgp 서명이 필수이다.

따라서 GPG key를 생성해야 한다.

아래에서 GPG를 설치할 수 있다.

https://gnupg.org/download/index.html#sec-1-2

GnuPG - Download

window의 경우 Gpg4Win을 설치하면 된다.

설치 후 아래 명령어를 사용하여 이름과 이메일, 관련 암호를 설정한다.

gpg --gen-key

 

GPG public key 등록

생성된 gpg key의 public key를 GPG keyserver에 등록해야 한다.

window라면 설치한  Gpg4Win 프로그램을 실행하여 내보내기를 하면 .asc 확장자의 공개키 파일을 따로 저장하게 된다.

이 공개키를 키 서버에 배포해야 하는데 maven central repository가 지원하는 GPG keyserver는 아래 3군데가 있다.

• keyserver.ubuntu.com
• keys.openpgp.org
• pgp.mit.edu

내 경우 keyserver.pgp.com에 파일 업로드 형식으로 등록하였다.

등록에 별다른 복잡한 절차는 없고 그냥 생성된 asc파일을 업로드만 하면 된다.

명령어를 통해서도 등록을 할 수 있다고 한다.

gpg --keyserver keyserver.ubuntu.com --send-keys CA925CD6C9E8D064FF05B4728190C4130ABA0F98

이렇게 3개 GPG keyserver 중 아무 곳이나 등록을 하면 이후 maven deploy 시 3군데를 순차적으로 검색하여 내 GPG key를 확인하게 된다.

project deploy를 위한 설정 (Maven 기준)

이제 프로젝트의 deploy를 위한 설정을 추가로 진행하면 된다.

maven, gradle, ant, sbt, 수동 배포에 대한 가이드를 제공해주는데 내 경우 maven project였기 때문에 maven 기준 문서를 참고하였다.

https://central.sonatype.org/publish/publish-maven/

Apache Maven - The Central Repository Documentation

2021년 2월 이후 https://s01.oss.sonatype.org 가 새롭게 제공되었다.

따라서 아래처럼 관련 배포 설정을 한다.

<distributionManagement>
  <snapshotRepository>
    <id>ossrh</id>
    <url>https://s01.oss.sonatype.org/content/repositories/snapshots</url>
  </snapshotRepository>
</distributionManagement>
<build>
  <plugins>
    <plugin>
      <groupId>org.sonatype.plugins</groupId>
      <artifactId>nexus-staging-maven-plugin</artifactId>
      <version>1.6.8</version>
      <extensions>true</extensions>
      <configuration>
        <serverId>ossrh</serverId>
        <nexusUrl>https://s01.oss.sonatype.org/</nexusUrl>
        <autoReleaseAfterClose>true</autoReleaseAfterClose>
      </configuration>
    </plugin>
    ...
  </plugins>
</build>

위의 경우 distributionManagement에 snapshot 배포에 대한 설정만 있는데 release 배포까지 하려면 아래처럼 repository 추가를 해야 한다.

<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>

이렇게 설정된 repository로 배포를 하기 위해 maven .m2 디렉터리에 settings.xml을 설정해야 한다.

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

username과 password에 생성한 Sonatype 계정 정보를 추가한다.

release 배포의 경우 javadoc과 source jar를 제공해야 하기 때문에 아래의 plugin 설정을 추가한다.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-source-plugin</artifactId>
    <version>3.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>3.3.0</version>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
</plugin>

GPG 서명을 사용하기 위해 아래 plugin을 추가한다.

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-gpg-plugin</artifactId>
      <version>1.6</version>
      <executions>
        <execution>
          <id>sign-artifacts</id>
          <phase>verify</phase>
          <goals>
            <goal>sign</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

해당 gpg plugin이 사용할 정보를 .m2 디렉터리의 settings.xml에 설정한다.

window의 경우 실행 파일 위치를 대략 아래와 같이 명시해야 한다.

<settings>
  <profiles>
    <profile>
      <id>ossrh</id>
      <activation>
        <activeByDefault>true</activeByDefault>
      </activation>
      <properties>
        <gpg.executable>C:\Program Files (x86)\GnuPG\bin\gpg.exe</gpg.executable>
        <gpg.passphrase>gpg비밀번호</gpg.passphrase>
      </properties>
    </profile>
  </profiles>
</settings>

만약 gpg key를 여러 개 가지고 있는 경우 사용할 key를 지정해야 하는데 관련 내용은 가이드 문서에 설명되어 있다.

여기까지 설정을 하였으면 일단 snapshot 배포는 정상적으로 동작한다. (만약 동작하지 않는다면 설치한 gpg 프로그램kleopatra가 실행 중인지 확인하여야 한다.)

프로젝트의 version이 -SNAPSHOT으로 끝나는 경우 아래처럼 배포를 실행하면 snapshot repository (https://s01.oss.sonatype.org/)에 정상적으로 등록된 것을 확인할 수 있다.

mvn clena deploy

release 배포의 경우 staging repository에 먼저 배포된 이후 추가적인 처리를 통해 release 배포를 하게 된다.

하지만 가이드 문서에는 자동으로 release에 배포되도록 nexus-staging-maven-plugin 사용을 안내하고 있다.

<build>
<plugins>
...
<plugin>
  <groupId>org.sonatype.plugins</groupId>
  <artifactId>nexus-staging-maven-plugin</artifactId>
  <version>1.6.8</version>
  <extensions>true</extensions>
  <configuration>
     <serverId>ossrh</serverId>
     <nexusUrl>https://s01.oss.sonatype.org/</nexusUrl>
     <autoReleaseAfterClose>true</autoReleaseAfterClose>
  </configuration>
</plugin>

위 설정을 추가하고 프로젝트의 version이 -SNAPSHOT이 아니면 release 버전으로 배포가 되게 된다.

---

2022-06-30 추가

오래간만에 maven central repository에 업로드하려고 하니 nexus-staging-maven-plugin 아래와 같은 에러가 발생했다.

[ERROR] Failed to execute goal org.sonatype.plugins:nexus-staging-maven-plugin:1.6.8:deploy (injected-nexus-deploy) on project bluesky-boot-autoconfigure-devcheck: Execution injected-nexus-deploy of goal org.sonatype.plugins:nexus-staging-maven-plugin:1.6.8:deploy failed: An API incompatibility was encountered while executing org.sonatype.plugins:nexus-staging-maven-plugin:1.6.8:deploy: java.lang.ExceptionInInitializerError: null

찾아보니 해당 플러그인을 오래된 버전을 사용해서 그런 거라고 한다.

https://stackoverflow.com/questions/70153962/nexus-staging-maven-plugin-maven-deploy-failed-an-api-incompatibility-was-enco

사용하는 plugin의 버전을 다음과 같이 변경하니 정상적으로 업로드가 된다.

<properties>
    <maven-plugin-plugin.version>3.6.4</maven-plugin-plugin.version>
    <nexus-staging-maven-plugin.version>1.6.13</nexus-staging-maven-plugin.version>
    <maven-gpg-plugin.version>3.0.1</maven-gpg-plugin.version>
    <maven-release-plugin.version>2.5.3</maven-release-plugin.version>
</properties>