使用Token通过GitHub Actions推送镜像至Docker Hub失败

问题分析 #

错误unauthorized: access token has insufficient scopes本质是推送镜像时使用的令牌没有目标仓库的写入权限，结合你的流水线配置，主要排查以下几个核心点：

核心解决步骤 #

1. 必须添加仓库登录步骤 #

docker/build-push-action不会自动完成仓库认证，需要先通过docker/login-action完成登录，分两种仓库场景处理：

场景A：推送到GitHub Container Registry（GHCR）

添加登录步骤，并赋予GITHUB_TOKEN包写入权限：

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      packages: write  # 给GITHUB_TOKEN添加包写入权限
    steps:
    - uses: actions/checkout@v3
    - name: Log in to GHCR
      uses: docker/login-action@v3
      with:
        registry: ghcr.io
        username: ${{ github.actor }}
        password: ${{ secrets.GITHUB_TOKEN }}
    - name: Build and push
      uses: docker/build-push-action@v5
      with:
        context: .
        push: true
        tags: ghcr.io/${{ github.repository_owner }}/${{ github.event.repository.name }}:${{ github.run_number }}
        build-args: |
          DB_PASSWORD=${{ secrets.DB_PASSWORD }}

场景B：推送到Docker Hub

使用Docker Hub的令牌登录，注意标签必须包含你的Docker Hub用户名：

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Log in to Docker Hub
      uses: docker/login-action@v3
      with:
        username: ${{ secrets.DOCKER_HUB_USERNAME }}
        password: ${{ secrets.DOCKER_HUB_TOKEN }}
    - name: Build and push
      uses: docker/build-push-action@v5
      with:
        context: .
        push: true
        tags: ${{ secrets.DOCKER_HUB_USERNAME }}/${{ github.event.repository.name }}:${{ github.run_number }}
        build-args: |
          DB_PASSWORD=${{ secrets.DB_PASSWORD }}

2. 修正镜像标签格式 #

• GHCR标签必须带ghcr.io/用户名/仓库名前缀，否则会默认推送到无权限的公共库
• Docker Hub标签必须带用户名/仓库名前缀，避免因仓库归属问题触发权限校验失败

3. 移除冗余构建步骤 #

你原配置中先执行docker build再用docker/build-push-action是重复操作，后者已包含完整的构建逻辑，直接通过build-args传递参数即可。

额外校验点 #

• 如果是GHCR，确认目标仓库已创建，且当前用户拥有仓库写入权限
• 如果是Docker Hub，检查令牌是否关联了目标仓库的读写权限（在Docker Hub仓库设置中确认）

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