使用 Maven 发布 Java 包

您可以使用 Maven 将 Java 包发布到注册表，作为持续集成 (CI) 工作流的一部分。

本文内容

简介

本指南将向您展示如何创建发布 Java 包到 GitHub Packages 和 Maven Central 存储库的工作流。使用单个工作流，您可以将包发布到单个存储库或多个存储库。

先决条件

我们建议您具备工作流文件和配置选项的基本了解。有关更多信息，请参阅“编写工作流”。

有关使用 Maven 为您的 Java 项目创建 CI 工作流的更多信息，请参阅“使用 Maven 构建和测试 Java”。

您可能还会发现了解以下内容很有帮助：

关于包配置

pom.xml 文件中的 groupId 和 artifactId 字段为您的软件包创建了一个唯一标识符，注册表使用该标识符将您的软件包链接到注册表。有关更多信息，请参阅 Apache Maven 文档中的 将构件上传到中央存储库指南。

pom.xml 文件还包含 Maven 将软件包部署到的分发管理存储库的配置。每个存储库都必须具有名称和部署 URL。这些存储库的身份验证可以在运行 Maven 的用户的 home 目录中的 .m2/settings.xml 文件中配置。

您可以使用 setup-java 操作来配置部署存储库以及该存储库的身份验证。有关更多信息，请参阅 setup-java。

将软件包发布到 Maven 中央存储库

每次创建新版本时，您都可以触发一个工作流来发布您的软件包。以下示例中的工作流在 release 事件触发且类型为 created 时运行。如果 CI 测试通过，则工作流会将软件包发布到 Maven 中央存储库。有关 release 事件的更多信息，请参阅“触发工作流的事件”。

在此工作流中，您可以使用 setup-java 操作。此操作会将给定版本的 JDK 安装到 PATH 中，但它还会为发布软件包配置 Maven settings.xml。默认情况下，设置文件将配置为 GitHub Packages，但可以将其配置为部署到其他软件包注册表，例如 Maven 中央存储库。如果您已经在 pom.xml 中配置了分发管理存储库，则可以在 setup-java 操作调用期间指定该 id。

例如，如果您要通过 OSSRH 托管项目部署到 Maven 中央存储库，则您的 pom.xml 可以指定一个 id 为 ossrh 的分发管理存储库。

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

使用此配置，您可以通过将存储库管理 id 指定给 setup-java 操作来创建将您的软件包发布到 Maven 中央存储库的工作流。您还需要提供包含用户名和密码的环境变量以对存储库进行身份验证。

在部署步骤中，您需要将环境变量设置为用于对存储库进行身份验证的用户名，以及使用您已配置的密码或令牌进行身份验证的密钥。有关更多信息，请参阅“在 GitHub Actions 中使用密钥”。

YAML
name: Publish package to the Maven Central Repository
on:
  release:
    types: [created]
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - 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 }}

此工作流执行以下步骤

  1. 检出项目存储库的副本。

  2. 设置 Java JDK，并配置 Maven settings.xml 文件以使用 MAVEN_USERNAME 和 MAVEN_PASSWORD 环境变量添加 ossrh 存储库的身份验证。

  3. 运行 mvn --batch-mode deploy 命令以发布到 ossrh 存储库。MAVEN_USERNAME 环境变量将设置为您的 OSSRH_USERNAME 密钥的内容，MAVEN_PASSWORD 环境变量将设置为您的 OSSRH_TOKEN 密钥的内容。

    有关在工作流中使用密钥的更多信息，请参阅“在 GitHub Actions 中使用密钥”。

将软件包发布到 GitHub Packages

每次创建新版本时，您都可以触发一个工作流来发布您的软件包。以下示例中的工作流在 release 事件触发且类型为 created 时运行。如果 CI 测试通过，则工作流会将软件包发布到 GitHub Packages。有关 release 事件的更多信息，请参阅“触发工作流的事件”。

在此工作流中，您可以使用 setup-java 操作。此操作会将给定版本的 JDK 安装到 PATH 中，还会设置一个 Maven settings.xml 以将软件包发布到 GitHub Packages。生成的 settings.xml 使用 GITHUB_ACTOR 环境变量作为用户名，使用 GITHUB_TOKEN 环境变量作为密码，为 id 为 github 的服务器定义身份验证。GITHUB_TOKEN 环境变量被分配特殊 GITHUB_TOKEN 密钥的值。

GITHUB_TOKEN 密钥在工作流中的作业开始时每次都被设置为存储库的访问令牌。您应该在工作流文件中设置此访问令牌的权限，以授予 contents 权限的读取访问权限和 packages 权限的写入访问权限。有关更多信息，请参阅“自动令牌身份验证”。

对于基于 Maven 的项目，您可以通过在 pom.xml 文件中创建一个 id 为 github 并指向您的 GitHub Packages 端点的分发存储库来利用这些设置。

例如，如果您的组织名为“octocat”，您的存储库名为“hello-world”，则 pom.xml 中的 GitHub Packages 配置将类似于以下示例。

XML
<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 的工作流。

YAML
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@v4
      - 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 }}

此工作流执行以下步骤

  1. 检出项目存储库的副本。

  2. 设置 Java JDK，并自动配置 Maven settings.xml 文件以添加 github Maven 存储库的身份验证，以便使用 GITHUB_TOKEN 环境变量。

  3. 运行 mvn --batch-mode deploy 命令以发布到 GitHub Packages。GITHUB_TOKEN 环境变量将设置为 GITHUB_TOKEN 密钥的内容。permissions 密钥指定授予 GITHUB_TOKEN 的访问权限。

    有关在工作流中使用密钥的更多信息，请参阅“在 GitHub Actions 中使用密钥”。

将软件包发布到 Maven 中央存储库和 GitHub Packages

您可以通过对每个注册表使用 setup-java 操作，将软件包发布到 Maven 中央存储库和 GitHub Packages。

确保您的 pom.xml 文件包含 GitHub 存储库和 Maven 中央存储库提供程序的分发管理存储库。例如，如果您通过 OSSRH 托管项目部署到中央存储库，则可能希望在 id 设置为 ossrh 的分发管理存储库中指定它，并且可能希望在 id 设置为 github 的分发管理存储库中指定 GitHub Packages。

YAML
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@v4
      - 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 以及用户名和密码。

此工作流执行以下步骤

  1. 检出项目存储库的副本。

  2. 第一次调用 setup-java。这将为 ossrh 存储库配置 Maven settings.xml 文件，并将身份验证选项设置为下一步中定义的环境变量。

  3. 运行 mvn --batch-mode deploy 命令以发布到 ossrh 存储库。MAVEN_USERNAME 环境变量将设置为您的 OSSRH_USERNAME 密钥的内容，MAVEN_PASSWORD 环境变量将设置为您的 OSSRH_TOKEN 密钥的内容。

  4. 第二次调用 setup-java。这将自动为 GitHub Packages 配置 Maven settings.xml 文件。

  5. 运行 mvn --batch-mode deploy 命令以发布到 GitHub Packages。GITHUB_TOKEN 环境变量将设置为 GITHUB_TOKEN 密钥的内容。permissions 密钥指定授予 GITHUB_TOKEN 的访问权限。

    有关在工作流中使用密钥的更多信息，请参阅“在 GitHub Actions 中使用密钥”。