Maven으로 Java 패키지 게시하기

이 튜토리얼에서는 지속적 통합(CI) 워크플로우의 일부로 Maven을 사용해서 Java 패키지를 레지스트리에 게시하는 방법을 알려드릴게요.

출처: 문서

본문

Introduction

이 가이드는 Java 패키지를 GitHub Packages와 Maven Central Repository에 게시하는 워크플로우를 만드는 방법을 보여줍니다. 단일 워크플로우로 하나의 저장소 또는 여러 저장소에 패키지를 게시할 수 있어요.

[!WARNING] 이 가이드에 사용된 예시는 Legacy OSSRH 서비스를 참조해요. Maven Central Repository 문서의 Publishing을 참고하세요.

Prerequisites

워크플로우 파일과 구성 옵션에 대한 기본적인 이해가 있으면 좋아요. 자세한 내용은 Writing workflows 문서를 참고하세요.

Maven으로 Java 프로젝트를 위한 CI 워크플로우를 만드는 방법에 대한 자세한 내용은 Building and testing Java with Maven 문서를 참고하세요.

다음에 대한 기본적인 이해가 있으면 더 도움이 될 수 있어요.

About package configuration

pom.xml 파일의 groupId 및 artifactId 필드는 레지스트리가 패키지를 레지스트리에 연결하는 데 사용하는 패키지의 고유 식별자를 만들어요. 자세한 내용은 Apache Maven 문서의 Guide to uploading artifacts to the Central Repository를 참고하세요.

[!WARNING] Apache Maven 패키지는 명명 규칙을 따라야 하므로 artifactId 필드에는 소문자, 숫자, 하이픈만 포함되어야 해요. 자세한 내용은 maven.apache.org 문서의 Naming convention of Maven coordinates를 참고하세요. 아티팩트 이름에 대문자를 사용하면 422 Unprocessable Entity 응답을 받게 돼요.

pom.xml 파일에는 Maven이 패키지를 배포할 배포 관리 저장소(distribution management repositories)에 대한 구성도 포함되어 있어요. 각 저장소에는 이름과 배포 URL이 있어야 해요. 이러한 저장소에 대한 인증은 Maven을 실행하는 사용자의 홈 디렉터리에 있는 .m2/settings.xml 파일에서 구성할 수 있어요.

setup-java 액션을 사용해서 배포 저장소와 해당 저장소에 대한 인증을 구성할 수 있어요. 자세한 내용은 setup-java을 참고하세요.

Publishing packages to the Maven Central Repository

새 릴리스를 만들 때마다 패키지를 게시하도록 워크플로우를 트리거할 수 있어요. 아래 예시의 워크플로우는 release 이벤트가 created 유형으로 트리거될 때 실행돼요. 워크플로우는 CI 테스트가 통과하면 패키지를 Maven Central Repository에 게시해요. release 이벤트에 대한 자세한 내용은 Events that trigger workflows 문서를 참고하세요.

이 워크플로우에서 setup-java 액션을 사용할 수 있어요. 이 액션은 지정된 JDK 버전을 PATH에 설치할 뿐만 아니라 패키지 게시를 위한 Maven settings.xml도 구성해요. 기본적으로 settings 파일은 GitHub Packages용으로 구성되지만, Maven Central Repository 같은 다른 패키지 레지스트리에 배포하도록 구성할 수도 있어요. pom.xml에 이미 배포 관리 저장소가 구성되어 있다면 setup-java 액션 호출 중에 해당 id를 지정할 수 있어요.

예를 들어 OSSRH 호스팅 프로젝트를 통해 Maven Central Repository에 배포한다면 pom.xml에서 id가 ossrh인 배포 관리 저장소를 지정할 수 있어요.

<project ...>
  ...
  <distributionManagement>
    <repository>
      <id>ossrh</id>
      <name>Central Repository OSSRH</name>
      <url>https://oss.sonatype.org/service/local/staging/deploy/maven2/</url>
    </repository>
  </distributionManagement>
</project>

이 구성으로 setup-java 액션에 저장소 관리 id를 지정해서 패키지를 Maven Central Repository에 게시하는 워크플로우를 만들 수 있어요. 또한 저장소에 인증하기 위한 사용자 이름과 비밀번호를 포함한 환경 변수를 제공해야 해요.

배포 단계에서 환경 변수를 저장소에 인증하는 사용자 이름과, 비밀번호 또는 토큰으로 인증하도록 구성한 secret으로 설정해야 해요. 자세한 내용은 Using secrets in GitHub Actions 문서를 참고하세요.

name: Publish package to the Maven Central Repository
on:
  release:
    types: [created]
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Set up Maven Central Repository
        uses: actions/setup-java@v4
        with:
          java-version: '11'
          distribution: 'temurin'
          server-id: ossrh
          server-username: MAVEN_USERNAME
          server-password: MAVEN_PASSWORD
      - name: Publish package
        run: mvn --batch-mode deploy
        env:
          MAVEN_USERNAME: ${{ secrets.OSSRH_USERNAME }}
          MAVEN_PASSWORD: ${{ secrets.OSSRH_TOKEN }}

이 워크플로우는 다음 단계를 수행해요.

프로젝트 저장소의 사본을 체크아웃합니다.
Java JDK를 설정하고, MAVEN_USERNAME 및 MAVEN_PASSWORD 환경 변수를 사용해서 ossrh 저장소에 대한 인증을 추가하도록 Maven settings.xml 파일도 구성해요.
mvn --batch-mode deploy 명령을 실행해서 ossrh 저장소에 게시합니다. MAVEN_USERNAME 환경 변수는 OSSRH_USERNAME secret의 내용으로 설정되고, MAVEN_PASSWORD 환경 변수는 OSSRH_TOKEN secret의 내용으로 설정돼요.

워크플로우에서 secret을 사용하는 방법에 대한 자세한 내용은 Using secrets in GitHub Actions 문서를 참고하세요.

Publishing packages to GitHub Packages

새 릴리스를 만들 때마다 패키지를 게시하도록 워크플로우를 트리거할 수 있어요. 아래 예시의 워크플로우는 release 이벤트가 created 유형으로 트리거될 때 실행돼요. 워크플로우는 CI 테스트가 통과하면 패키지를 GitHub Packages에 게시해요. release 이벤트에 대한 자세한 내용은 Events that trigger workflows 문서를 참고하세요.

이 워크플로우에서 setup-java 액션을 사용할 수 있어요. 이 액션은 지정된 JDK 버전을 PATH에 설치하고, 패키지를 GitHub Packages에 게시하기 위한 Maven settings.xml도 설정해요. 생성된 settings.xml은 GITHUB_ACTOR 환경 변수를 사용자 이름으로, GITHUB_TOKEN 환경 변수를 비밀번호로 사용해서 id가 github인 서버에 대한 인증을 정의해요. GITHUB_TOKEN 환경 변수에는 특수 GITHUB_TOKEN secret의 값이 할당돼요.

GITHUB_TOKEN secret은 워크플로우의 각 job이 시작될 때마다 저장소에 대한 액세스 토큰으로 설정돼요. contents 권한에 대한 읽기 액세스와 packages 권한에 대한 쓰기 액세스를 부여하도록 워크플로우 파일에서 이 액세스 토큰의 권한을 설정해야 해요. 자세한 내용은 Use GITHUB_TOKEN for authentication in workflows 문서를 참고하세요.

Maven 기반 프로젝트의 경우 pom.xml 파일에 GitHub Packages 엔드포인트를 가리키는 id가 github인 배포 저장소를 만들어 이러한 설정을 활용할 수 있어요.

예를 들어 조직 이름이 "octocat"이고 저장소 이름이 "hello-world"라면 pom.xml의 GitHub Packages 구성은 아래 예시와 유사할 거예요.

<project ...>
  ...
  <distributionManagement>
    <repository>
      <id>github</id>
      <name>GitHub Packages</name>
      <url>https://maven.pkg.github.com/octocat/hello-world</url>
    </repository>
  </distributionManagement>
</project>

이 구성으로 자동 생성된 settings.xml을 사용해서 패키지를 GitHub Packages에 게시하는 워크플로우를 만들 수 있어요.

name: Publish package to GitHub Packages
on:
  release:
    types: [created]
jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-java@v4
        with:
          java-version: '11'
          distribution: 'temurin'
      - name: Publish package
        run: mvn --batch-mode deploy
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

이 워크플로우는 다음 단계를 수행해요.

프로젝트 저장소의 사본을 체크아웃합니다.
Java JDK를 설정하고, github Maven 저장소가 GITHUB_TOKEN 환경 변수를 사용하도록 인증을 추가하는 Maven settings.xml 파일도 자동으로 구성해요.
mvn --batch-mode deploy 명령을 실행해서 GitHub Packages에 게시합니다. GITHUB_TOKEN 환경 변수는 GITHUB_TOKEN secret의 내용으로 설정돼요. permissions 키는 GITHUB_TOKEN에 부여된 접근을 지정해요.

워크플로우에서 secret을 사용하는 방법에 대한 자세한 내용은 Using secrets in GitHub Actions 문서를 참고하세요.

Publishing packages to the Maven Central Repository and GitHub Packages

각 레지스트리에 대해 setup-java 액션을 사용해서 Maven Central Repository와 GitHub Packages 양쪽 모두에 패키지를 게시할 수 있어요.

pom.xml 파일에 GitHub 저장소와 Maven Central Repository 제공자 모두에 대한 배포 관리 저장소가 포함되어 있는지 확인하세요. 예를 들어 OSSRH 호스팅 프로젝트를 통해 Central Repository에 배포한다면 id가 ossrh로 설정된 배포 관리 저장소에 지정하고, GitHub Packages는 id가 github로 설정된 배포 관리 저장소에 지정할 수 있어요.

name: Publish package to the Maven Central Repository and GitHub Packages
on:
  release:
    types: [created]
jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v6
      - name: Set up Java for publishing to Maven Central Repository
        uses: actions/setup-java@v4
        with:
          java-version: '11'
          distribution: 'temurin'
          server-id: ossrh
          server-username: MAVEN_USERNAME
          server-password: MAVEN_PASSWORD
      - name: Publish to the Maven Central Repository
        run: mvn --batch-mode deploy
        env:
          MAVEN_USERNAME: ${{ secrets.OSSRH_USERNAME }}
          MAVEN_PASSWORD: ${{ secrets.OSSRH_TOKEN }}
      - name: Set up Java for publishing to GitHub Packages
        uses: actions/setup-java@v4
        with:
          java-version: '11'
          distribution: 'temurin'
      - name: Publish to GitHub Packages
        run: mvn --batch-mode deploy
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

이 워크플로우는 setup-java 액션을 두 번 호출해요. setup-java 액션이 실행될 때마다 패키지 게시용 Maven settings.xml 파일을 덮어써요. 저장소에 대한 인증을 위해 settings.xml 파일은 배포 관리 저장소 id와 사용자 이름 및 비밀번호를 참조해요.

이 워크플로우는 다음 단계를 수행해요.

프로젝트 저장소의 사본을 체크아웃합니다.
setup-java를 처음 호출합니다. 이는 ossrh 저장소용 Maven settings.xml 파일을 구성하고, 인증 옵션을 다음 단계에서 정의되는 환경 변수로 설정해요.
mvn --batch-mode deploy 명령을 실행해서 ossrh 저장소에 게시합니다. MAVEN_USERNAME 환경 변수는 OSSRH_USERNAME secret의 내용으로 설정되고, MAVEN_PASSWORD 환경 변수는 OSSRH_TOKEN secret의 내용으로 설정돼요.
setup-java를 두 번째 호출합니다. 이는 GitHub Packages용 Maven settings.xml 파일을 자동으로 구성해요.
mvn --batch-mode deploy 명령을 실행해서 GitHub Packages에 게시합니다. GITHUB_TOKEN 환경 변수는 GITHUB_TOKEN secret의 내용으로 설정돼요. permissions 키는 GITHUB_TOKEN에 부여된 접근을 지정해요.

워크플로우에서 secret을 사용하는 방법에 대한 자세한 내용은 Using secrets in GitHub Actions 문서를 참고하세요.

Maven으로 Java 패키지 게시하기