使用 Gradle 发布 Java 包

本文内容

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

简介

本指南介绍如何创建将 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 中心仓库

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

你可以在指向包存储库的 build.gradle 文件的发布块中定义一个新的 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

# 此工作流使用未经 GitHub 认证的操作。
# 它们由第三方提供，并受
# 单独的服务条款、隐私政策和支持
# 文档。

# GitHub 建议将操作固定到提交 SHA。
# 若要获取较新版本，需要更新 SHA。
# 还可以引用标记或分支，但该操作可能会更改而不发出警告。

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@v3
        with:
          java-version: '11'
          distribution: 'temurin'
      - name: Validate Gradle wrapper
        uses: gradle/wrapper-validation-action@ccb4328a959376b642e027874838f60f8e596de3
      - name: Publish package
        uses: gradle/gradle-build-action@749f47bda3e44aa060e82d7b3ef7e40d953bd629
        with:
          arguments: publish
        env:
          MAVEN_USERNAME: ${{ secrets.OSSRH_USERNAME }}
          MAVEN_PASSWORD: ${{ secrets.OSSRH_TOKEN }}

此工作流程执行以下步骤：

  1. 检出项目仓库的副本。

  2. 设置 Java JDK。

  3. 验证仓库中存在的 Gradle Wrapper JAR 文件的校验和。

  4. 使用 publish 参数运行 gradle/gradle-build-action 操作以发布到 OSSRH Maven 存储库。 MAVEN_USERNAME 环境变量将使用 OSSRH_USERNAME 机密的内容进行设置，MAVEN_PASSWORD 环境变量将使用 OSSRH_TOKEN 机密的内容进行设置。

    有关在工作流中使用机密的详细信息，请参阅“在 GitHub Actions 中使用机密”。

发布包到 GitHub Packages

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

可以在指向 GitHub Packages 的 build.gradle 的发布块中定义一个新的 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

# 此工作流使用未经 GitHub 认证的操作。
# 它们由第三方提供，并受
# 单独的服务条款、隐私政策和支持
# 文档。

# GitHub 建议将操作固定到提交 SHA。
# 若要获取较新版本，需要更新 SHA。
# 还可以引用标记或分支，但该操作可能会更改而不发出警告。

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@v3
        with:
          java-version: '11'
          distribution: 'temurin'
      - name: Validate Gradle wrapper
        uses: gradle/wrapper-validation-action@ccb4328a959376b642e027874838f60f8e596de3
      - name: Publish package
        uses: gradle/gradle-build-action@749f47bda3e44aa060e82d7b3ef7e40d953bd629
        with:
          arguments: publish
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

此工作流程执行以下步骤：

  1. 检出项目仓库的副本。

  2. 设置 Java JDK。

  3. 验证仓库中存在的 Gradle Wrapper JAR 文件的校验和。

  4. 使用 publish 参数运行 gradle/gradle-build-action 操作以发布到 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

# 此工作流使用未经 GitHub 认证的操作。
# 它们由第三方提供，并受
# 单独的服务条款、隐私政策和支持
# 文档。

# GitHub 建议将操作固定到提交 SHA。
# 若要获取较新版本，需要更新 SHA。
# 还可以引用标记或分支，但该操作可能会更改而不发出警告。

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@v3
        with:
          java-version: '11'
          distribution: 'temurin'
      - name: Validate Gradle wrapper
        uses: gradle/wrapper-validation-action@ccb4328a959376b642e027874838f60f8e596de3
      - name: Publish package
        uses: gradle/gradle-build-action@749f47bda3e44aa060e82d7b3ef7e40d953bd629
        with:
          arguments: publish
        env: 
          MAVEN_USERNAME: ${{ secrets.OSSRH_USERNAME }}
          MAVEN_PASSWORD: ${{ secrets.OSSRH_TOKEN }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

此工作流程执行以下步骤：

  1. 检出项目仓库的副本。

  2. 设置 Java JDK。

  3. 验证仓库中存在的 Gradle Wrapper JAR 文件的校验和。

  4. 使用 publish 参数运行 gradle/gradle-build-action 操作以发布到 OSSRH Maven 存储库和 GitHub Packages。 MAVEN_USERNAME 环境变量将使用 OSSRH_USERNAME 机密的内容进行设置，MAVEN_PASSWORD 环境变量将使用 OSSRH_TOKEN 机密的内容进行设置。 GITHUB_TOKEN 环境变量将使用 GITHUB_TOKEN 机密的内容进行设置。 permissions 密钥指定 GITHUB_TOKEN 机密允许的访问。

    有关在工作流中使用机密的详细信息，请参阅“在 GitHub Actions 中使用机密”。