使用GitHub Actions登录GHCR遇权限拒绝：最佳实践与组织凭证登录

一、错误原因分析 #

你遇到的denied: denied错误，大概率是以下原因之一：

• 所用的个人访问令牌（PAT）权限不足，缺少write:packages或repo等必要权限
• 登录时的用户名（github.actor）与PAT所属用户不匹配（PR触发时github.actor是PR发起者，而PAT是其他成员的）
• PAT所属用户没有该组织仓库的镜像推送权限

二、最佳实践方案 #

1. 优先使用GitHub官方的GITHUB_TOKEN #

这是最推荐的方式，无需手动创建和维护令牌，安全且适配性强：

• GITHUB_TOKEN是GitHub Actions自动生成的临时令牌，权限仅限当前仓库，工作流结束后自动失效
• 需要在工作流中明确配置所需权限，遵循最小权限原则
• 示例代码：

name: Build and publish Docker image
on:
  push:
    branches: [ main ] # 仅在main分支提交时触发
jobs:
  publish-docker-image:
    runs-on: ubuntu-latest
    permissions:
      contents: read # 拉取代码所需权限
      packages: write # 推送镜像到GHCR所需权限
    steps:
    - uses: actions/checkout@v4
    - name: Login to GitHub Container Registry
      uses: docker/login-action@v3
      with:
        registry: ghcr.io
        username: ${{ github.actor }}
        password: ${{ secrets.GITHUB_TOKEN }}
    # 后续添加镜像构建和推送步骤
    - name: Build & Push Docker Image
      uses: docker/build-push-action@v5
      with:
        context: .
        push: true
        tags: ghcr.io/[你的组织名]/[你的仓库名]:latest

2. 若必须使用个人访问令牌（PAT） #

如果因特殊需求必须使用PAT，遵循以下规则：

• 创建组织专属的机器人用户（而非成员个人账号），用该账号生成PAT，避免成员离职导致令牌失效
• 给PAT授予最小必要权限：至少包含write:packages、read:packages，如果需要拉取私有仓库代码，还需添加repo权限
• 确保令牌所属用户在组织中拥有仓库的写入权限，以及GHCR的镜像推送权限
• 登录时用户名必须与PAT所属用户一致，不能用github.actor（避免PR触发时用户名不匹配）

三、关于组织凭证的使用 #

可以使用组织级别的凭证登录，推荐两种方式：

1. 组织机器人用户的PAT：创建一个属于组织的机器人账号，生成该账号的PAT作为登录凭证，这种方式简单易维护
2. GitHub Apps：对于更复杂的权限管理场景，可创建组织级GitHub Apps，生成安装令牌用于登录，安全性更高，但配置步骤相对繁琐

不过对于大部分场景，使用GITHUB_TOKEN已经足够满足需求，它代表的github-actions[bot]在组织仓库中默认具备相应权限，只要配置好permissions字段即可。

内容的提问来源于stack exchange，提问作者schaffsp