使用 Gradle 发布 Java 包

你可以使用 Gradle 在持续集成 (CI) 工作流中将 Java 包发布到注册表。

本文中

简介

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

先决条件

我们建议你对工作流文件和配置选项有基本的了解。有关详细信息，请参阅“了解 GitHub Actions”。

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

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

关于包配置

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

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

将软件包发布到 Maven Central 存储库

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

可以在 build.gradle 文件的发布块中定义一个指向软件包存储库的新 Maven 存储库。例如，如果要通过 OSSRH 托管项目将软件包部署到 Maven Central 存储库，则 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 Central 存储库的工作流。在部署步骤中，需要为用于向 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@417ae3ccd767c252f5661f1ace9f835f9654f2b5 # v3.1.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

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

可以在 build.gradle 的发布块中定义一个指向 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@417ae3ccd767c252f5661f1ace9f835f9654f2b5 # v3.1.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 Central 存储库和 GitHub Packages

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

确保你的 build.gradle 文件包含一个存储库，用于你的 GitHub 存储库和 Maven Central 存储库提供程序。

例如，如果你通过 OSSRH 托管项目部署到 Central Repository，你可能希望在分发管理存储库中指定它，其中 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 Central Repository 和 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@417ae3ccd767c252f5661f1ace9f835f9654f2b5 # v3.1.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 中使用机密”。