自建GitLab CE运行测试CI流水线报错求助

常见报错场景与处理方案 #

1. Runner注册失败/离线 #

• 核心现象：流水线提示无可用Runner，或Runner状态显示离线
• 处理步骤：
  • 先验证网络连通性：在Runner主机执行 ping <GitLab实例IP/域名>，确认能正常访问GitLab
  • 重新注册Runner：从GitLab项目「设置-CI/CD-Runners」获取注册令牌，在Runner主机运行 gitlab-runner register，按提示输入GitLab地址、令牌、Runner标签及执行器（如shell、docker）
  • 检查Runner服务状态：执行 gitlab-runner status，异常则重启服务 gitlab-runner restart

2. .gitlab-ci.yml语法错误 #

• 核心现象：流水线初始化阶段直接失败，提示配置文件语法问题
• 处理步骤：
  • 用GitLab内置工具校验：在项目根目录执行 gitlab-ci-lint（需先装GitLab CLI），或直接在项目CI/CD设置页的「CI Lint」功能验证
  • 检查YAML缩进：必须用2个空格（禁止制表符），确保各层级结构正确
  • 核对关键字拼写：比如把script写成scirpt、stage和stages混淆这类低级错误

3. Shell执行器权限不足 #

• 核心现象：流水线执行命令时提示「Permission denied」，无法写入文件或执行系统命令
• 处理步骤：
  • 调整Runner用户权限：将默认的gitlab-runner用户加入对应权限组，比如 usermod -aG sudo gitlab-runner（按需调整）
  • 修复项目目录权限：执行 chown -R gitlab-runner:gitlab-runner <项目本地路径>，确保Runner用户能访问
  • 配置免密sudo（如需）：编辑/etc/sudoers，添加 gitlab-runner ALL=(ALL) NOPASSWD: ALL，避免脚本中sudo命令需要输入密码

4. Docker执行器镜像拉取失败 #

• 核心现象：流水线提示无法拉取指定Docker镜像
• 处理步骤：
  • 检查Docker服务状态：执行 systemctl status docker，异常则重启 systemctl restart docker
  • 配置私有仓库认证：编辑/etc/gitlab-runner/config.toml，在[[runners]]节点下添加pull_policy = "if-not-present"，并在docker子节点配置auth_config填写仓库账号密码
  • 手动测试拉取：执行 docker pull <镜像名:标签>，确认镜像名称、标签正确且网络能访问仓库

5. GitLab实例内部服务异常 #

• 核心现象：流水线无响应、提示「500 Internal Server Error」
• 处理步骤：
  • 检查GitLab组件状态：执行 gitlab-ctl status，确认sidekiq、gitlab-workhorse等核心组件正常运行
  • 查看日志定位问题：执行 gitlab-ctl tail，重点关注CI相关日志条目
  • 清理缓存并重启：执行 gitlab-rake cache:clear，再运行 gitlab-ctl restart 重启GitLab服务

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