使用 Gradle 发布 Java 包

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

本文内容

简介

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

先决条件

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

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

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

关于包配置

build.gradle 文件中 `MavenPublication` 部分的 `groupId` 和 `artifactId` 字段为您的包创建了一个唯一标识符，注册表使用此标识符将您的包链接到注册表。这类似于 Maven pom.xml 文件的 `groupId` 和 `artifactId` 字段。更多信息，请参阅 Gradle 文档中的“Maven 发布插件”。

build.gradle 文件还包含 Gradle 将发布包到的分发管理存储库的配置。每个存储库必须具有名称、部署 URL 和身份验证凭据。

将包发布到 Maven 中央存储库

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

您可以在 build.gradle 文件的 publishing 块中定义一个指向您的包存储库的新 Maven 存储库。例如，如果您通过 OSSRH 托管项目部署到 Maven 中央存储库，您的 build.gradle 可以指定一个名为 `OSSRH` 的存储库。

Groovy
plugins {
  ...
  id 'maven-publish'
}

publishing {
  ...

  repositories {
    maven {
      name = "OSSRH"
      url = "https://oss.sonatype.org/service/local/staging/deploy/maven2/"
      credentials {
        username = System.getenv("MAVEN_USERNAME")
        password = System.getenv("MAVEN_PASSWORD")
      }
    }
  }
}

通过此配置，您可以创建一个工作流，通过运行 `gradle publish` 命令将您的包发布到 Maven 中央存储库。在部署步骤中，您需要为用于向 Maven 存储库进行身份验证的用户名和密码或令牌设置环境变量。更多信息，请参阅“在 GitHub Actions 中使用密钥”。

YAML

# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.

# GitHub recommends pinning actions to a commit SHA.
# To get a newer version, you will need to update the SHA.
# You can also reference a tag or branch, but the action may change without warning.

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 Java
        uses: actions/setup-java@v4
        with:
          java-version: '11'
          distribution: 'temurin'

      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@af1da67850ed9a4cedd57bfd976089dd991e2582 # v4.0.0

      - name: Publish package
        run: ./gradlew publish
        env:
          MAVEN_USERNAME: ${{ secrets.OSSRH_USERNAME }}
          MAVEN_PASSWORD: ${{ secrets.OSSRH_TOKEN }}

此工作流执行以下步骤

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

  2. 设置 Java JDK。

  3. 设置 Gradle 环境。gradle/actions/setup-gradle 操作负责在工作流运行之间缓存状态，并提供所有 Gradle 执行的详细摘要。

  4. 执行 Gradle `publish` 任务以发布到 `OSSRH` Maven 存储库。`MAVEN_USERNAME` 环境变量将设置为您的 `OSSRH_USERNAME` 密钥的内容，`MAVEN_PASSWORD` 环境变量将设置为您的 `OSSRH_TOKEN` 密钥的内容。

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

将包发布到 GitHub Packages

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

您可以在 build.gradle 的 publishing 块中定义一个指向 GitHub Packages 的新 Maven 存储库。在该存储库配置中，您还可以利用在 CI 工作流运行中设置的环境变量。您可以使用 `GITHUB_ACTOR` 环境变量作为用户名，并使用您的 `GITHUB_TOKEN` 密钥设置 `GITHUB_TOKEN` 环境变量。

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

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

Groovy
plugins {
  ...
  id 'maven-publish'
}

publishing {
  ...

  repositories {
    maven {
      name = "GitHubPackages"
      url = "https://maven.pkg.github.com/octocat/hello-world"
      credentials {
        username = System.getenv("GITHUB_ACTOR")
        password = System.getenv("GITHUB_TOKEN")
      }
    }
  }
}

通过此配置，您可以创建一个工作流，通过运行 `gradle publish` 命令将您的包发布到 GitHub Packages。

YAML

# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.

# GitHub recommends pinning actions to a commit SHA.
# To get a newer version, you will need to update the SHA.
# You can also reference a tag or branch, but the action may change without warning.

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: Setup Gradle
        uses: gradle/actions/setup-gradle@af1da67850ed9a4cedd57bfd976089dd991e2582 # v4.0.0

      - name: Publish package
        run: ./gradlew publish
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

此工作流执行以下步骤

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

  2. 设置 Java JDK。

  3. 设置 Gradle 环境。gradle/actions/setup-gradle 操作负责在工作流运行之间缓存状态，并提供所有 Gradle 执行的详细摘要。

  4. 执行 Gradle `publish` 任务以发布到 GitHub Packages。`GITHUB_TOKEN` 环境变量将设置为 `GITHUB_TOKEN` 密钥的内容。`permissions` 密钥指定 `GITHUB_TOKEN` 密钥将允许的访问权限。

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

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

您可以通过在 build.gradle 文件中配置每个存储库来将包发布到 Maven 中央存储库和 GitHub Packages。

确保您的 build.gradle 文件包含 GitHub 存储库和 Maven 中央存储库提供程序的存储库。

例如，如果您通过 OSSRH 托管项目部署到中央存储库，则可能需要在分发管理存储库中将其指定为 `name` 设置为 `OSSRH`。如果您部署到 GitHub Packages，则可能需要在分发管理存储库中将其指定为 `name` 设置为 `GitHubPackages`。

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

Groovy
plugins {
  ...
  id 'maven-publish'
}

publishing {
  ...

  repositories {
    maven {
      name = "OSSRH"
      url = "https://oss.sonatype.org/service/local/staging/deploy/maven2/"
      credentials {
        username = System.getenv("MAVEN_USERNAME")
        password = System.getenv("MAVEN_PASSWORD")
      }
    }
    maven {
      name = "GitHubPackages"
      url = "https://maven.pkg.github.com/octocat/hello-world"
      credentials {
        username = System.getenv("GITHUB_ACTOR")
        password = System.getenv("GITHUB_TOKEN")
      }
    }
  }
}

通过此配置，您可以创建一个工作流，通过运行 `gradle publish` 命令将您的包发布到 Maven 中央存储库和 GitHub Packages。

YAML

# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.

# GitHub recommends pinning actions to a commit SHA.
# To get a newer version, you will need to update the SHA.
# You can also reference a tag or branch, but the action may change without warning.

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
        uses: actions/setup-java@v4
        with:
          java-version: '11'
          distribution: 'temurin'
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@af1da67850ed9a4cedd57bfd976089dd991e2582 # v4.0.0

      - name: Publish package
        run: ./gradlew publish
        env: 
          MAVEN_USERNAME: ${{ secrets.OSSRH_USERNAME }}
          MAVEN_PASSWORD: ${{ secrets.OSSRH_TOKEN }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

此工作流执行以下步骤

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

  2. 设置 Java JDK。

  3. 设置 Gradle 环境。gradle/actions/setup-gradle 操作负责在工作流运行之间缓存状态，并提供所有 Gradle 执行的详细摘要。

  4. 执行 Gradle `publish` 任务以发布到 `OSSRH` Maven 存储库和 GitHub Packages。`MAVEN_USERNAME` 环境变量将设置为您的 `OSSRH_USERNAME` 密钥的内容，`MAVEN_PASSWORD` 环境变量将设置为您的 `OSSRH_TOKEN` 密钥的内容。`GITHUB_TOKEN` 环境变量将设置为 `GITHUB_TOKEN` 密钥的内容。`permissions` 密钥指定 `GITHUB_TOKEN` 密钥将允许的访问权限。

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