使用GitHub Actions推送Docker镜像失败：令牌权限不足

问题概述 #

通过GitHub Actions构建Docker镜像并推送至Docker Hub时，出现如下权限错误：

The push refers to repository [docker.io/***/java-app]
d1eab8b60748: Waiting
unauthorized: access token has insufficient scopes
Error: Process completed with exit code 1.

已在GitHub Secrets中配置DOCKERHUB_USERNAME及具备读、写、删除权限的访问令牌（对应DOCKERHUB_PASSWORD），但问题仍存在。

以下是我的GitHub Actions配置（main.yml）：

name: Docker

on:
  push:
    branches:
      - master

env:
  # TODO: Change variable to your image's name.
  IMAGE_NAME: java-app

jobs:
  push:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Build image
        run: docker build --file ./docker/Dockerfile --tag ${{ env.IMAGE_NAME }} .

      - name: Log into registry
        run: docker login -u ${{ secrets.DOCKERHUB_USERNAME }} -p ${{ secrets.DOCKERHUB_PASSWORD }} registry.hub.docker.com
  
      - name: Push image
        run: |
          IMAGE_ID=${{ secrets.DOCKERHUB_USERNAME }}/qfix-test
          # Strip git ref prefix from version
          VERSION=$(echo \"${{ github.ref }}\" | sed -e 's,.*/\(.*\),\1,')
          # Strip \"v\" prefix from tag name
          [[ \"${{ github.ref }}\" == \"refs/tags/\"* ]] && VERSION=$(echo $VERSION | sed -e 's/^v//')
          # Use Docker `latest` tag convention
          [ \"$VERSION\" == \"master\" ] && VERSION=latest
          echo IMAGE_ID=$IMAGE_ID
          echo VERSION=$VERSION

          docker tag ${{ env.IMAGE_NAME }} $IMAGE_ID:$VERSION
          docker push $IMAGE_ID:$VERSION

排查步骤 #

1. 修正脚本中的冗余转义问题 #

配置中push步骤的脚本里，双引号前的反斜杠是多余的，会导致变量解析异常：
原错误代码片段：

VERSION=$(echo \"${{ github.ref }}\" | sed -e 's,.*/\(.*\),\1,')
[[ \"${{ github.ref }}\" == \"refs/tags/\"* ]] && VERSION=$(echo $VERSION | sed -e 's/^v//')
[ \"$VERSION\" == \"master\" ] && VERSION=latest

修正为：

VERSION=$(echo "${{ github.ref }}" | sed -e 's,.*/\(.*\),\1,')
[[ "${{ github.ref }}" == "refs/tags/"* ]] && VERSION=$(echo $VERSION | sed -e 's/^v//')
[ "$VERSION" == "master" ] && VERSION=latest

冗余转义会让VERSION变量包含引号，导致[ "$VERSION" == "master" ]判断失败，无法切换到latest标签，可能引发权限验证异常。

2. 核对Docker Hub仓库权限 #

• 确认Docker Hub上已创建qfix-test仓库（对应脚本中的IMAGE_ID=${{ secrets.DOCKERHUB_USERNAME }}/qfix-test），首次推送时若仓库不存在，需要令牌具备创建仓库的全局权限；
• 检查Docker Hub访问令牌的权限范围：确保令牌关联到你的账号，且权限覆盖qfix-test仓库（或设置为全局读写权限），避免令牌仅授权了其他特定仓库。

3. 验证令牌的有效性 #

在本地环境测试令牌是否能正常推送：

# 登录Docker Hub
docker login -u 你的DockerHub用户名 -p 你的访问令牌 registry.hub.docker.com
# 打标签并推送
docker tag java-app 你的DockerHub用户名/qfix-test:latest
docker push 你的DockerHub用户名/qfix-test:latest

• 若本地推送失败：说明令牌本身权限配置错误或已过期，需重新生成权限正确的令牌；
• 若本地推送成功：检查GitHub Secrets是否配置正确（比如DOCKERHUB_USERNAME/DOCKERHUB_PASSWORD拼写错误、令牌包含多余空格或换行）。

4. 确认镜像仓库匹配 #

错误日志中显示的仓库是docker.io/***/java-app，但脚本中指定的是qfix-test，需确认：

• 脚本中的docker tag命令是否正确执行，确保镜像标签是用户名/qfix-test:版本而非java-app；
• 检查IMAGE_NAME变量是否干扰了标签生成，确保最终推送的镜像仓库与Docker Hub上的仓库一致。

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