本教程旨在解决github actions中maven项目在拉取github packages私有依赖时遇到的401 unauthorized认证失败问题。文章将深入分析问题根源，并提供通过配置`github_token`环境变量来正确认证访问github packages的详细解决方案，包括工作流代码示例和重要的注意事项，确保您的ci/cd流程顺畅运行。
问题描述：Maven项目在GitHub Actions中遭遇401认证失败
在使用GitHub Actions为Java Maven项目设置持续集成（CI）环境时，开发者可能会遇到一个常见的构建失败问题，尤其当项目依赖于存储在GitHub Packages中的私有Maven包时。典型的错误信息如下所示：
Error: Failed to execute goal on project example: Could not resolve dependencies for project <dependency>: Failed to collect dependencies at <dependency>: Failed to read artifact descriptor for <dependency>: Could not transfer artifact <dependency> from/to github (https://maven.pkg.github.com/example/package/): authentication failed for https://maven.pkg.github.com/example/package/.../<dependency>.pom, status: 401 Unauthorized -> [Help 1]
这个错误表明，GitHub Actions工作流在尝试从https://maven.pkg.github.com拉取私有依赖时，未能通过认证，导致HTTP 401 Unauthorized状态码。尽管本地Maven构建可能通过~/.m2/settings.xml中的凭据正常工作，但在GitHub Actions环境中，默认情况下这些凭据并未自动配置。
根本原因分析
GitHub Packages是一个包管理服务，允许用户托管私有和公共包。为了访问私有包，无论是下载还是发布，都需要进行身份验证。在本地开发环境中，通常通过在Maven的settings.xml文件中配置server和repository信息，并使用个人访问令牌（Personal Access Token, PAT）或用户名/密码进行认证。
然而，GitHub Actions的运行器（runner）是一个临时的、隔离的环境。它不会自动继承本地开发机器上的settings.xml配置。因此，当工作流尝试从GitHub Packages拉取私有依赖时，由于缺乏必要的认证凭据，GitHub Packages服务会拒绝请求，返回401 Unauthorized错误。
解决方案：通过GITHUB_TOKEN进行认证
解决此问题的核心在于向GitHub Actions工作流提供一个有效的认证令牌，使其能够访问GitHub Packages。GitHub Actions提供了一个内置的令牌GITHUB_TOKEN，它在每个工作流运行开始时自动生成，并具有针对当前仓库的特定权限。对于访问同一仓库或同一组织/用户下的GitHub Packages，GITHUB_TOKEN通常是足够且推荐的解决方案。
实践步骤与代码示例
以下是如何修改您的GitHub Actions工作流以解决401认证失败问题的步骤。
原始工作流示例
一个典型的、可能导致上述错误的Maven构建工作流如下：
name: Java CI with Maven
on:
push:
branches: [ "master" ]
pull_request:
branches: [ "master" ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up JDK 11
uses: actions/setup-java@v3
with:
java-version: '11'
distribution: 'temurin'
cache: maven
- name: Build with Maven
run: mvn -B package --file pom.xml修改后的工作流
为了允许Maven在构建过程中访问GitHub Packages，我们需要在执行mvn命令的步骤中，通过环境变量将GITHUB_TOKEN传递进去。Maven本身并不直接识别GITHUB_TOKEN，但它可以通过settings.xml配置来使用它。actions/setup-java这个Action会自动配置一个settings.xml文件，使其能够利用GITHUB_TOKEN进行GitHub Packages的认证。
name: Java CI with Maven
on:
push:
branches: [ "master" ]
pull_request:
branches: [ "master" ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up JDK 11
uses: actions/setup-java@v3
with:
java-version: '11'
distribution: 'temurin'
cache: maven
# 这一行是关键：确保Maven能够认证GitHub Packages
# actions/setup-java 会自动配置一个settings.xml，使用GITHUB_TOKEN
# 如果需要发布包，可能需要额外配置GPG签名等
- name: Build with Maven
env:
# 将GITHUB_TOKEN作为环境变量传递给Maven构建过程
# secrets.GITHUB_TOKEN 是GitHub Actions内置的令牌
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: mvn -B package --file pom.xml在上述修改后的工作流中，关键在于Build with Maven步骤下的env块：
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}这行代码将GitHub Actions内置的GITHUB_TOKEN作为名为GITHUB_TOKEN的环境变量传递给了mvn -B package命令。当actions/setup-java配置Maven环境时，它会检测到这个环境变量，并自动在生成的settings.xml中添加一个server配置，使用GITHUB_TOKEN进行GitHub Packages的认证。
理解GITHUB_TOKEN
- secrets.GITHUB_TOKEN: 这是GitHub Actions提供的一个内置令牌，在每次工作流运行时自动生成。它的权限范围仅限于当前仓库，并且根据工作流触发事件和仓库设置具有不同的默认权限。对于拉取当前仓库或同一组织/用户下其他仓库的私有GitHub Packages，通常具有足够的读取权限。
- 自定义PAT (Personal Access Token): 如果您的项目需要访问不同组织或用户下的私有GitHub Packages，或者需要发布包到GitHub Packages，并且GITHUB_TOKEN的默认权限不足以满足要求，您可能需要创建一个具有read:packages或write:packages（或repo）权限的个人访问令牌（PAT），并将其作为仓库秘密（Repository Secret）存储，例如secrets.MY_PAT。然后，在工作流中像这样使用它：GITHUB_TOKEN: ${{ secrets.MY_PAT }}。但请注意，使用PAT会增加安全风险，因为它拥有更广泛的权限，且不会自动过期，应谨慎使用并定期轮换。
注意事项与最佳实践
权限最小化原则: 优先使用secrets.GITHUB_TOKEN，因为它具有最小的必要权限，且仅在工作流运行期间有效，安全性更高。只有当GITHUB_TOKEN的权限不足时，才考虑使用自定义PAT。
actions/setup-java的作用: actions/setup-java不仅设置了Java环境，它还智能地处理了Maven的settings.xml配置，以便与GitHub Packages协同工作。确保您使用了这个Action。
-
Maven pom.xml配置: 确保您的pom.xml文件中包含了正确的GitHub Packages仓库配置，例如：
<repositories> <repository> <id>github</id> <name>GitHub Packages</name> <url>https://maven.pkg.github.com/OWNER/REPOSITORY</url> </repository> </repositories> <distributionManagement> <repository> <id>github</id> <name>GitHub Packages</name> <url>https://maven.pkg.github.com/OWNER/REPOSITORY</url> </repository> </distributionManagement>请将OWNER和REPOSITORY替换为您的实际用户名/组织名和仓库名。id必须与settings.xml中server的id匹配。actions/setup-java会自动生成一个settings.xml，其中id通常是github。
调试: 如果问题依然存在，可以尝试在构建步骤前添加一个步骤，打印settings.xml的内容（例如，cat ~/.m2/settings.xml），以验证actions/setup-java是否正确配置了认证信息。
总结
在GitHub Actions中构建Maven项目并依赖GitHub Packages私有包时，遇到401认证失败是一个常见问题。通过理解其根本原因——缺乏正确的认证凭据，并采用GITHUB_TOKEN环境变量作为解决方案，可以有效地解决这一挑战。secrets.GITHUB_TOKEN是首选且安全的认证机制，它简化了CI/CD流程中的私有依赖管理。遵循本文提供的步骤和最佳实践，可以确保您的GitHub Actions工作流能够顺畅地拉取和构建Maven项目，从而实现高效的持续集成。
