CICD实例：解决GitLab Runner无法执行CICD问题

本文介绍解决GitLab Runner无法执行CICD问题的过程。具体来说，是GitLab Runner服务启动失败，导致Git仓库的构建流水的Job一直处理Pending状态。

问题现象

在GitLab Runner命令行中注册了runner，接着提交代码到关联的Git仓库，但 Job 一直卡在 Pending 状态，页面提示：

复制代码

This job has not started yet
This job is in pending state and is waiting to be picked by a runner

与此同时，GitLab 仓库的 Runners 页面显示 Runner 图标为灰色三角叹号，鼠标悬停提示 not connected yet。等待一段时间后图标变为绿色，但 Job 依然 Pending。runner状态的图标示例如下。

排查过程

确认 Runner 服务状态

在安装Runner的服务器上执行以下命令：

复制代码

$ sudo gitlab-runner status
Runtime platform arch=amd64 os=linux pid=2915803 revision=3153ccc6 version=17.7.0
gitlab-runner: Service is running

笔者机器上输出显示 Service is running，看上去一切正常，但是，页面仍显示未连接。

验证 Runner 连接

接着查看状态：

复制代码

sudo gitlab-runner verify
运行时平台                                 架构=amd64 操作系统=linux 进程ID=2919743 修订版本=3153ccc6 版本=17.7.0
正在以系统模式运行。

正在验证运行器... 存活                                runner=Z9Ru5W9m
正在验证运行器... 存活                                runner=cWfYdzZ2

输出显示 Runner cWfYdzZ2 为 存活 状态，说明网络和 Token 均正常。但页面状态与命令结果不一致，说明问题不在连接层面。只能继续排查。

查看系统日志

接着查看运行日志：

复制代码

$ sudo journalctl -u gitlab-runner -f
Starting multi-runner from /etc/gitlab-runner/config.toml...  builds=0 max_builds=0
Running in system-mode.
FATAL: Service run failed  error=chdir /home/gitlab-runner: no such file or directory
systemd[1]: gitlab-runner.service: Main process exited, code=exited, status=1/FAILURE
systemd[1]: gitlab-runner.service: Failed with result 'exit-code'.

在日志中看到服务退出了，关键的错误信息为chdir /home/gitlab-runner: no such file or directory。因此，问题已经很明确了：/home/gitlab-runner 目录不存在，导致 Runner 服务启动时无法切换工作目录，进程直接退出。

原因分析

gitlab-runner 的 systemd 服务默认以 gitlab-runner 用户运行，其HOME目录为 /home/gitlab-runner。经查，该目录缺失的常见原因：

手动安装二进制文件时未自动创建用户和家目录
系统清理或误操作删除了该目录
用户创建时未使用 --create-home 参数

笔者的情况是，因为前一台机器出问题，切换了新机器，但在安装过程中，没有指定目录（即没有使用--create-home 参数），导致服务启动即失败，虽然gitlab-runner status 显示了 running 状态，runner也存活，但实际已无法正常执行CICD流程。

解决方案

知道了原因，解决方法就很简单了。

创建缺失的目录：

复制代码

sudo mkdir -p /home/gitlab-runner
sudo chmod 755 /home/gitlab-runner

注：本次不创建使用gitlab-runner用户。

重启服务：

复制代码

sudo systemctl daemon-reload
sudo systemctl restart gitlab-runner
sudo systemctl status gitlab-runner

如果看到输出：Active: active (running)，说明服务启动成功。

最后通过查看日志确认启动是否成功：

复制代码

sudo journalctl -u gitlab-runner -n 30 --no-pager

期望看到：

复制代码

Configuration loaded  builds=0
Running in system-mode.

不再出现 FATAL: chdir /home/gitlab-runner 错误。

在 GitLab 仓库的CICD配置页面，应该能看到 Runner 为绿色。

结语

当时切换机器时，由于着急使用CICD构建（要在服务器上编译ARM平台的程序），没有细看当初写的安装步骤。为何没有创建/home/gitlab-runner目录，已不可考。虽然花了时间排查问题，但能让自己从另一个层面重新了解GitLab Runner，也是个不错的经历。