GitLab Runner镜像无法执行Maven构建、作业未匹配Runner问题咨询

按优先级从高到低依次排查以下问题：

1. 标签匹配规则校验 #

• 逐字符核对.gitlab-ci.yml中Maven作业的tags字段，与Runner配置页标注的标签是否完全一致，标签区分大小写，不要带看不见的前后空格，最稳妥的方式是两边都复制粘贴同一段标签文本，避免手动输入出错
• 检查Runner配置页是否勾选了Run untagged jobs：如果没勾选，所有没有配置对应标签的作业都不会调度到该Runner；要么给Maven作业补上匹配的标签，要么开启该选项允许Runner接收无标签作业
• 确认Runner归属正确：要在当前项目的Runners列表里能看到该Runner，如果是实例级共享Runner，要确认项目没有开启Disable shared Runners开关

2. Runner运行状态校验 #

• 进入项目Settings > CI/CD > Runners页面，查看目标Runner的状态标识，如果是灰色离线状态：
  • 如果是裸机部署的Runner，登录部署机器执行gitlab-runner status检查服务状态，服务未启动则执行gitlab-runner start拉起
  • 如果是Docker方式启动的Runner镜像，执行docker ps查看容器是否正常运行，容器异常退出时执行docker logs <runner容器ID/名称>查看报错，常见问题为注册时填的GitLab地址/Token错误、配置目录挂载权限不足
• 若Runner显示在线但接不到作业，登录Runner部署端执行gitlab-runner verify，检查与GitLab实例的通信是否正常，通信异常时重新注册Runner即可

3. 调度权限冲突校验 #

• 若Runner被标记为Protected，只有运行在受保护分支/受保护标签上的作业才能调度到该Runner，非受保护分支触发的Maven作业不会匹配，要么取消Runner的保护标记，要么将对应分支设置为受保护分支
• 检查.gitlab-ci.yml中Maven作业是否配置了特殊执行器要求，比如作业指定了需要Docker执行器，但你注册的Runner是Shell执行器，也会出现匹配失败的问题

4. Maven构建场景特殊排查 #

• 如果是Docker执行器的Runner，确认Maven作业中配置的基础镜像可正常拉取，镜像拉取失败会导致作业启动失败，容易被误判为Runner匹配不到，可先在Runner所在机器手动执行docker pull maven:3.8-openjdk-11测试镜像拉取能力
• 检查Runner所在节点的磁盘、CPU、内存资源是否充足，资源耗尽时Runner会自动暂停接收新作业，表现为作业一直处于待调度状态

快速定位技巧：先写一个最小测试作业，只配置和目标Runner一致的标签，执行命令填echo "runner connect test"，提交代码触发作业。如果测试作业都无法调度，优先排查标签、Runner状态、权限问题；如果测试作业可以正常运行，再排查Maven作业本身的CI配置问题。

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