GitLab Runner无法从集成GitLab Registry拉取部分镜像

云上老周

2026-7-14

GitLab CI拉取Registry镜像部分失败排查

问题现象

部分镜像可正常拉取，日志示例：

Running with gitlab-runner 16.2.0 (782e15da)   
  on org-docker-runner-dev Cz4fZWrV, system ID: s_ab8104dd6bf6 
Preparing the "docker+machine" executor 00:02 
Using Docker executor with image registry.gitlab.com/org/microservices/tf-runner:0.1.1 ...
WARNING: Container based cache volumes creation is disabled. Will not create volume for "/certs/client" 
Authenticating with credentials from job payload (GitLab Registry) 
Pulling docker image registry.gitlab.com/org/microservices/tf-runner:0.1.1 ... 
Using docker image sha256:ffd931f7c294dcd42a82579a65c1693ed1ddb2bfc1b6b95fd51bf24c66350d99 for registry.gitlab.com/org/microservices/tf-runner:0.1.1 with digest registry.gitlab.com/org/microservices/tf-runner@sha256:4b937f08deb883ffd5d4f135ed30b0fbe46719e1e09ba55e01bb9811367730c9 ... 
...

对应配置：

image: $CI_REGISTRY/org/microservices/tf-runner:0.1.1

但拉取另一镜像时认证失败，日志示例：

Running with gitlab-runner 16.2.0 (782e15da)   
  on org-docker-runner-dev Cz4fZWrV, system ID: s_ab8104dd6bf6
Preparing the "docker+machine" executor 00:02
Using Docker executor with image registry.gitlab.com/org/microservices/kubectl:0.0.2 ...
WARNING: Container based cache volumes creation is disabled. Will not create volume for "/certs/client"
Authenticating with credentials from job payload (GitLab Registry)
Pulling docker image registry.gitlab.com/org/microservices/kubectl:0.0.2 ...

WARNING: Failed to pull image with policy "always": Error response from daemon: pull access denied for registry.gitlab.com/org/microservices/kubectl, repository does not exist or may require 'docker login': denied: requested access to the resource is denied (manager.go:237:1s)

ERROR: Job failed: failed to pull image "registry.gitlab.com/org/microservices/kubectl:0.0.2" with specified policies [always]: Error response from daemon: pull access denied for registry.gitlab.com/org/microservices/kubectl, repository does not exist or may require 'docker login': denied: requested access to the resource is denied (manager.go:237:1s)

对应配置：

image: $CI_REGISTRY/org/microservices/kubectl:0.0.2

已配置DOCKER_AUTH_CONFIG变量（Base64编码的username:password），本地可使用相同凭证拉取，但CI仍失败，以下是可能的排查方向：

镜像仓库权限不匹配
CI作业默认使用CI_JOB_TOKEN拉取同项目/组的镜像，该令牌权限仅限于当前项目。如果kubectl镜像所在项目与CI作业项目不属于同一组，或该项目设为私有且未授权当前CI项目访问，就会触发权限拒绝。即便配置了DOCKER_AUTH_CONFIG，也可能因Runner优先使用内置的CI_JOB_TOKEN而未生效。
DOCKER_AUTH_CONFIG格式错误
正确的DOCKER_AUTH_CONFIG是完整JSON结构，而非单纯的Base64字符串。示例格式：
```
{
  "auths": {
    "registry.gitlab.com": {
      "auth": "Base64编码的username:token字符串"
    }
  }
}
```
若仅填写Base64编码值，Docker无法识别认证信息，导致拉取失败。
CI变量作用域未覆盖目标项目
如果kubectl镜像所在项目与CI作业项目不同，需确认DOCKER_AUTH_CONFIG变量的作用域是否包含目标项目或整个组。仅在单个项目下设置的变量无法被其他项目的CI作业调用。
Runner凭证优先级冲突
GitLab Runner会优先使用Job Payload中的CI_JOB_TOKEN进行Registry认证，即便配置了DOCKER_AUTH_CONFIG，也可能被内置凭证覆盖。可尝试在.gitlab-ci.yml中显式禁用自动认证，强制使用自定义凭证：
```
variables:
  GITLAB_REGISTRY_AUTO_DISABLED: "true"
```
Runner节点缓存或配置问题
使用docker+machine executor时，Machine节点可能存在旧的Docker认证缓存，导致新的DOCKER_AUTH_CONFIG未生效。可尝试重启Runner服务，或清理Machine节点的Docker认证缓存（删除~/.docker/config.json文件）。
镜像标签/路径的大小写问题
GitLab Registry对仓库路径和标签的大小写敏感，需确认CI配置中的路径、标签与Registry中的完全一致（例如避免Kubectl与kubectl的大小写差异）。

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

GitLab Runner无法从集成GitLab Registry拉取部分镜像

问题现象 #

问题现象