GitLab CI推送Docker镜像至Docker Hub遇权限拒绝错误求助

我之前也碰到过一模一样的坑，咱们一步步拆解排查：

1. 先核对GitLab CI变量的核心配置 #

首先确认你在GitLab项目的「Settings → CI/CD → Variables」里配置的DOCKER_USERNAME、DOCKER_PASSWORD，是不是和Docker Hub上添加为仓库协作者的账号完全一致——Docker Hub的用户名是大小写敏感的，输错大小写直接触发权限拒绝。

另外重点检查$REPOSITORY变量的格式：必须是仓库所有者的用户名/仓库名，比如仓库属于alice，你作为协作者推送，变量就得是alice/my-service，不能写成你自己的用户名开头。

2. 确保docker login步骤真的成功了 #

很多时候登录步骤静默失败，但脚本继续执行导致推送报错。可以在登录后加个验证输出，比如：

deploy:
  stage: deploy
  script:
    - docker login -u $DOCKER_USERNAME -p $DOCKER_PASSWORD
    - echo "✅ Docker Hub登录成功" # 登录失败会直接终止脚本，不会走到这一步
    - docker push $REPOSITORY:$CI_COMMIT_SHORT_SHA

去CI日志里看有没有这个成功提示，如果没有，说明登录环节就出问题了，大概率是凭据错了。

3. 本地手动验证协作者权限 #

Docker Hub的权限偶尔会有同步延迟，你可以用这个协作者账号在本地测试：

# 本地登录协作者账号
docker login -u 你的协作者用户名
# 给本地镜像打对应仓库的标签
docker tag 本地镜像名:标签 仓库所有者用户名/仓库名:标签
# 尝试推送
docker push 仓库所有者用户名/仓库名:标签

如果本地推送失败，直接去Docker Hub检查协作者权限——必须给的是读写权限，只读权限肯定推不了；如果本地能推，那问题就锁定在GitLab CI的配置上。

4. 检查镜像标签是否和目标仓库匹配 #

很多人会忽略镜像打标签的步骤：你构建出来的镜像名是my-app:latest，但直接推$REPOSITORY的话，Docker会默认用你的用户名去关联仓库，这时候如果仓库不属于你，就会报错。必须先给镜像打对应目标仓库的标签：

script:
  - docker build -t my-app .
  - docker tag my-app:latest $REPOSITORY:latest # 这一步不能少！
  - docker push $REPOSITORY:latest

5. 清理Runner的旧登录缓存 #

有时候GitLab Runner的环境里缓存了旧的Docker登录凭据，导致用了错误的账号登录。可以在脚本开头先登出：

script:
  - docker logout # 清除旧凭据
  - docker login -u $DOCKER_USERNAME -p $DOCKER_PASSWORD
  - docker push $REPOSITORY:$CI_COMMIT_SHORT_SHA

我当时就是把$REPOSITORY里的仓库所有者用户名写成了自己的，导致推送时用自己的账号去推别人的仓库，直接触发权限拒绝。你可以先从变量和标签这两个点入手排查，应该能快速解决问题~

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