GitHub Actions构建时无法拉取GHCR私有镜像，如何配置？

方案1：调整GITHUB_TOKEN的权限范围 #

默认生成的GITHUB_TOKEN权限仅覆盖当前仓库，无法访问组织内其他私有镜像。需在工作流开头添加权限声明，同时确保目标镜像的访问权限配置允许当前仓库读取：

步骤1：在工作流中添加权限配置 #

在工作流的最上方添加permissions字段，赋予包读取权限：

name: Build & Push Docker Image
on: [push, pull_request]

permissions:
  packages: read  # 核心：允许读取GHCR中的私有包
  contents: read  # 可选，用于拉取代码仓库内容

jobs:
  build-image:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Log in to GHCR
        uses: docker/login-action@v2
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      
      # 后续的metadata、build-push步骤保持不变

步骤2：配置目标私有镜像的访问权限 #

进入GHCR中ghcr.io/my-org/data镜像的管理页面：

• 点击「Package settings」
• 在「Manage access」区域，添加当前仓库（或组织内的团队），并授予Read权限

方案2：使用个人访问令牌（PAT）替代GITHUB_TOKEN #

如果跨组织/跨仓库的权限配置麻烦，可以生成拥有包读取权限的PAT：

1. 打开GitHub个人设置 → 「Developer settings」→ 「Personal access tokens」→ 生成新令牌
2. 勾选权限：read:packages（若需推送镜像则额外勾选write:packages）
3. 将令牌添加到当前仓库的Secrets中，命名为GHCR_PAT
4. 修改工作流的登录步骤：

- name: Log in to GHCR
  uses: docker/login-action@v2
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GHCR_PAT }}

方案3：排查Buildx缓存影响（可选） #

若使用Buildx缓存功能，可能出现认证信息未正确传递的情况。可在build-push-action中显式配置缓存并保留认证：

- name: Build and push Docker image
  uses: docker/build-push-action@v4
  with:
    push: true
    tags: ${{ steps.meta.outputs.tags }}
    labels: ${{ steps.meta.outputs.labels }}
    cache-from: type=gha
    cache-to: type=gha,mode=max

问题根源 #

本地构建正常是因为本地Docker已保存GHCR的登录认证信息；而GitHub Actions中的GITHUB_TOKEN是临时令牌，默认权限仅局限于当前仓库，跨资源访问私有包时需额外配置权限或使用权限更灵活的PAT。

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