# 使用 Gradle 发布Java包

本教程介绍如何使用 Gradle 将Java包作为持续集成（CI）工作流的一部分发布到注册表。

## 简介

本指南介绍如何创建将 Java 包发布到 GitHub Packages 和 Maven Central 仓库的工作流程。 通过单个工作流程，您可以将包发布到一个或多个仓库。

> \[!WARNING] 本指南中使用的示例指旧版 OSSRH 服务。 请参阅 Maven 中央存储库文档中“[发布](https://central.sonatype.org/faq/what-is-different-between-central-portal-and-legacy-ossrh/#publishing)”。

## 先决条件

建议对工作流程文件和配置选项有一个基本了解。 有关详细信息，请参阅“[撰写工作流程](/zh/actions/learn-github-actions)”。

有关使用 Gradle 为Java项目创建 CI 工作流的详细信息，请参阅 [使用 Gradle 构建和测试 Java](/zh/actions/automating-builds-and-tests/building-and-testing-java-with-gradle)。

你可能还发现基本了解以下内容是有帮助的：

* [使用 Apache Maven 注册表](/zh/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry)
* [在变量中存储信息](/zh/actions/learn-github-actions/variables)
* [在 GitHub Actions 中使用机密](/zh/actions/security-guides/using-secrets-in-github-actions)
* [在工作流中使用 GITHUB\_TOKEN 进行身份验证](/zh/actions/security-guides/automatic-token-authentication)

## 关于包配置

build.gradle 文件 `groupId` 部分中的 `artifactId` 和 `MavenPublication` 字段为包创建唯一标识符，注册表使用该标识符将包链接到注册表。 这类似于 Maven pom.xml 文件的 `groupId` 和 `artifactId` 字段。 有关详细信息，请参阅 Gradle 文档中的“[Maven Publish Plugin](https://docs.gradle.org/current/userguide/publishing_maven.html)”。

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

## 将包发布到 Maven 中心仓库

每次创建新版本时，都可以触发工作流程来发布包。 以下示例中的工作流在 `release` 事件以 `created` 类型触发时运行。 如果 CI 测试通过，工作流程将包发布到 Maven 中心仓库。 有关 `release` 事件的详细信息，请参阅“[触发工作流的事件](/zh/actions/using-workflows/events-that-trigger-workflows#release)”。

你可以在指向包存储库的 *build.gradle* 文件的发布块中定义一个新的 Maven 存储库。 例如，如果通过 OSSRH 托管项目部署到 Maven 中央存储库，则 build.gradle 可以指定名称为 \_\_ 的存储库。

```groovy copy
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 中使用机密](/zh/actions/security-guides/using-secrets-in-github-actions)”。

```yaml copy

# 此工作流使用未经 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@v6
      - name: Set up Java
        uses: actions/setup-java@v4
        with:
          java-version: '11'
          distribution: 'temurin'

      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@017a9effdb900e5b5b2fddfb590a105619dca3c3 # v4.4.2

      - 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`](https://github.com/gradle/actions) 操作负责工作流运行之间的缓存状态，并提供所有 Gradle 执行的详细摘要。
4. 执行 Gradle `publish` 任务以发布到 `OSSRH` Maven 存储库。
   `MAVEN_USERNAME` 环境变量将使用 `OSSRH_USERNAME` 机密的内容进行设置，`MAVEN_PASSWORD` 环境变量将使用 `OSSRH_TOKEN` 机密的内容进行设置。

   有关在工作流中使用机密的详细信息，请参阅“[在 GitHub Actions 中使用机密](/zh/actions/security-guides/using-secrets-in-github-actions)”。

## 将包发布到 GitHub Packages

每次创建新版本时，都可以触发工作流程来发布包。 以下示例中的工作流在 `release` 事件以 `created` 类型触发时运行。 如果 CI 测试通过，工作流程会将包发布到 GitHub Packages。 有关 `release` 事件的详细信息，请参阅“[触发工作流的事件](/zh/actions/using-workflows/events-that-trigger-workflows#release)”。

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

每当工作流中的作业开始时，`GITHUB_TOKEN` 机密都会设置为存储库的访问令牌。 应在工作流文件中设置此访问令牌的权限，以授予 `contents` 权限的读取访问权限，并授予 `packages` 权限的写入访问权限。 有关详细信息，请参阅“[在工作流中使用 GITHUB\_TOKEN 进行身份验证](/zh/actions/security-guides/automatic-token-authentication)”。

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

```groovy copy
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 copy

# 此工作流使用未经 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@v6
      - uses: actions/setup-java@v4
        with:
          java-version: '11'
          distribution: 'temurin'
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@017a9effdb900e5b5b2fddfb590a105619dca3c3 # v4.4.2

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

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

1. 检出项目仓库的副本。
2. 设置 Java JDK。
3. 设置 Gradle 环境。 [`gradle/actions/setup-gradle`](https://github.com/gradle/actions) 操作负责工作流运行之间的缓存状态，并提供所有 Gradle 执行的详细摘要。
4. 执行 Gradle `publish` 任务以发布到 GitHub Packages。
   `GITHUB_TOKEN` 环境变量将使用 `GITHUB_TOKEN` 机密的内容进行设置。
   `permissions` 密钥指定 `GITHUB_TOKEN` 机密允许的访问。

   有关在工作流中使用机密的详细信息，请参阅“[在 GitHub Actions 中使用机密](/zh/actions/security-guides/using-secrets-in-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 copy
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 copy

# 此工作流使用未经 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@v6
      - name: Set up Java
        uses: actions/setup-java@v4
        with:
          java-version: '11'
          distribution: 'temurin'
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@017a9effdb900e5b5b2fddfb590a105619dca3c3 # v4.4.2

      - 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`](https://github.com/gradle/actions) 操作负责工作流运行之间的缓存状态，并提供所有 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 中使用机密](/zh/actions/security-guides/using-secrets-in-github-actions)”。