简介
本指南介绍如何创建将 Java 包发布到 GitHub Packages 和 Maven Central 仓库的工作流程。 通过单个工作流程,您可以将包发布到一个或多个仓库。
先决条件
建议对工作流程文件和配置选项有一个基本了解。 有关详细信息,请参阅“写入工作流”。
有关使用 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"
的存储库。
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") } } } }
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 中使用机密”。
# 此工作流使用未经 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@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 认证的操作。
# 它们由第三方提供,并受
# 单独的服务条款、隐私政策和支持
# 文档。
# 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@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 }}
此工作流程执行以下步骤:
-
检出项目仓库的副本。
-
设置 Java JDK。
-
设置 Gradle 环境。
gradle/actions/setup-gradle
操作负责工作流运行之间的缓存状态,并提供所有 Gradle 执行的详细摘要。 -
执行 Gradle
publish
任务以发布到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 配置类似于以下示例。
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") } } } }
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。
# 此工作流使用未经 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@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 }}
# 此工作流使用未经 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@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 }}
此工作流程执行以下步骤:
-
检出项目仓库的副本。
-
设置 Java JDK。
-
设置 Gradle 环境。
gradle/actions/setup-gradle
操作负责工作流运行之间的缓存状态,并提供所有 Gradle 执行的详细摘要。 -
执行 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 中的配置类似于以下示例。
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") } } } }
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。
# 此工作流使用未经 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@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 }}
# 此工作流使用未经 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@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 }}
此工作流程执行以下步骤:
-
检出项目仓库的副本。
-
设置 Java JDK。
-
设置 Gradle 环境。
gradle/actions/setup-gradle
操作负责工作流运行之间的缓存状态,并提供所有 Gradle 执行的详细摘要。 -
执行 Gradle
publish
任务以发布到OSSRH
Maven 存储库和 GitHub Packages。MAVEN_USERNAME
环境变量将使用OSSRH_USERNAME
机密的内容进行设置,MAVEN_PASSWORD
环境变量将使用OSSRH_TOKEN
机密的内容进行设置。GITHUB_TOKEN
环境变量将使用GITHUB_TOKEN
机密的内容进行设置。permissions
密钥指定GITHUB_TOKEN
机密允许的访问。有关在工作流中使用机密的详细信息,请参阅“在 GitHub Actions 中使用机密”。