Gitlab Runner未拉取gitlab-ci.yml中定义的服务镜像求助

这种本地Runner正常、GitLab平台Runner不生效的情况我碰到过好几次，大概率是这几个配置细节没注意到，咱们逐一排查：

1. 检查Runner的Executor类型 #

本地Runner默认一般用的是docker executor，天然支持services容器；但GitLab平台上的Runner（不管是共享Runner还是你自己部署的群Runner）可能用了不支持services的executor，比如shell——这种模式直接在主机环境运行Job，不会启动独立的服务容器。

解决方法：

• 进入项目的Settings -> CI/CD -> Runners，查看关联Runner的Executor类型，确认是docker、docker+machine或kubernetes这类支持services的类型。
• 如果是自己部署的Runner，修改config.toml里的executor字段为docker，重启Runner生效。

2. 确认Services镜像的拉取权限 #

本地能拉取镜像可能是因为你已经在本地Docker客户端登录过私有仓库，但GitLab平台的Runner没有配置对应认证，导致拉取私有镜像失败（日志里可能有隐藏的错误）。

解决方法：

• 在项目的Settings -> CI/CD -> Variables里添加DOCKER_AUTH_CONFIG变量，值为本地~/.docker/config.json的完整内容（该文件包含私有仓库的认证信息）。
• 如果是公开镜像，检查镜像名是否拼写正确（比如大小写、标签是否存在）——本地可能有缓存镜像，平台Runner需要重新拉取，拼写错误会直接失败。

3. 检查Services的语法规范 #

本地Runner可能兼容一些不标准的写法，但GitLab平台的Runner对语法要求更严格。比如services的写法是否符合规范：

正确的写法示例：

# 基础写法
services:
  - mysql:8.0

# 带别名的写法
services:
  - name: mysql:8.0
    alias: database

解决方法：

• 查看CI Job的完整日志，搜索services相关条目，看是否有Failed to pull image或Invalid service configuration这类错误提示。
• 去掉services里的自定义参数（如果有的话），先用最简写法测试是否能拉取镜像。

4. 核对Runner与GitLab的版本兼容性 #

如果你的本地Runner版本和GitLab平台版本差距过大，可能存在services功能的兼容性问题——比如旧版本Runner对新的services语法支持有bug。

解决方法：

• 查看GitLab平台版本（Settings -> About），确保Runner版本与GitLab版本相差不超过1个大版本（比如GitLab是16.x，Runner最好用15.x或16.x）。
• 自己部署的Runner直接升级到对应版本；共享Runner由GitLab官方维护，一般会保持版本同步。

5. 检查Job的Tags匹配规则 #

如果你的Job指定了tags，但平台上匹配的Runner没有对应的tags，可能会被分配到不支持services的Runner上（比如你本地Runner有docker标签，平台Runner没有）。

解决方法：

• 去掉Job里的tags配置，让Job自动分配到GitLab官方共享Runner（默认支持services）测试。
• 如果必须用tags，确保平台上的Runner配置了对应的tags，且该Runner的executor支持services。

总结 #

优先查看CI Job的完整日志，找services相关的错误提示，再针对性排查上面的点——大部分情况都是权限不足、executor类型不对或tags匹配错误导致的。

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