GitHub Actions "Resource not accessible by integration" 错误解决方案

问题描述

当在 GitHub Actions 工作流中使用 ${{ secrets.GITHUB_TOKEN }} 调用 GitHub REST API 时，可能会遇到以下错误：

{
  "message": "Resource not accessible by integration",
  "documentation_url": "https://docs.github.com/rest/reference/actions#create-a-registration-token-for-a-repository"
}

这个错误通常发生在尝试调用需要特定权限的 API 端点时，而默认的 GITHUB_TOKEN 没有足够的权限。

错误原因

GITHUB_TOKEN 是 GitHub 自动为每个工作流运行生成的临时令牌，但其默认权限有限。默认情况下，它只有以下权限：

• contents: read - 读取内容
• metadata: read - 读取元数据

当尝试执行需要写入权限或其他特定权限的操作（如创建 runner 注册令牌）时，就会出现 "Resource not accessible by integration" 错误。

解决方案

方法一：在工作流中配置权限（推荐）

在作业级别添加 permissions 字段，明确指定所需权限：

jobs:
  print-token:
    runs-on: ubuntu-latest
    permissions:
      # 根据实际需要选择权限
      actions: write    # 管理 Actions
      contents: write   # 写入内容
      checks: write     # 管理检查
      packages: write   # 管理包
      id-token: write   # 写入 ID token
      attestations: write  # 写入证明

TIP

根据您的具体需求选择适当的权限组合，避免授予不必要的权限。

方法二：修改仓库级别的 Actions 设置

1. 进入仓库的 "Settings" → "Actions" → "General"
2. 找到 "Workflow permissions" 部分
3. 选择 "Read and write permissions" 选项
4. 保存设置

方法三：使用个人访问令牌 (PAT)

如果上述方法不适用，可以创建个人访问令牌：

1. 在 GitHub 设置中创建 Personal Access Token
2. 为令牌授予所需权限
3. 将令牌添加为仓库的 Secret
4. 在工作流中使用该令牌：

steps:
  - name: Get registration token
    run: |
      curl -X POST \
        -H "Accept: application/vnd.github.v3+json" \
        -H "Authorization: token ${{ secrets.YOUR_PAT }}" \
        https://api.github.com/repos/${{ github.repository }}/actions/runners/registration-token

WARNING

使用 PAT 时需要谨慎，因为它比 GITHUB_TOKEN 有更广泛的权限。确保只授予必要的权限。

权限配置参考

以下是一些常见场景所需的权限配置：

创建 Runner 注册令牌

permissions:
  actions: write

管理 Artifacts

permissions:
  actions: read
  contents: read

测试报告生成

permissions:
  contents: read
  actions: read
  checks: write

容器构建和推送

permissions:
  contents: read
  packages: write
  id-token: write
  attestations: write

最佳实践

1. 最小权限原则：只授予工作流所需的最小权限集
2. 作业级权限：在作业级别配置权限，而不是全局设置
3. 定期审查：定期审查工作流权限设置
4. 使用 GITHUB_TOKEN：优先使用 GITHUB_TOKEN 而不是 PAT，因为它更安全

注意

对于企业版私有仓库，某些权限可能有额外的限制。请查阅 GitHub Enterprise 文档了解详细信息。

故障排除

如果仍然遇到问题：

1. 检查 API 端点文档确认所需权限
2. 验证令牌是否有正确的范围
3. 确认仓库设置中没有覆盖工作流权限
4. 查看 GitHub Actions 运行日志获取更详细的错误信息

通过正确配置权限，您可以解决 "Resource not accessible by integration" 错误，使您的工作流能够成功调用 GitHub API。