gitlab-runner 再次实践中理解和学习

<花开花落>2025-10-03 11:52

文章目录

以前在 Mac、windows 上使用过 gitlab 的 pipeline，安装配置过 gitlab-runner，执行 pipeline 也没很多问题。现在需要在 Linux 上再走一遍流程，一开始觉得应该挺容易的，流程比较熟悉，和其他平台大致相似吧，应该很快就搞好了。

然而，这次遇到的问题还挺多的。实际操作时，发现有些不同，出现踩坑的原因也有环境的限制（部分网络无法访问），也有对 gitlab-runner 机制的不理解。现在整理一下遇到的问题吧。

背景

  • 环境网络设备特殊，很多要求权限的步骤，在普通用户下无法直接使用 sudo，只能在 root 账户下操作
  • 一台公共的 Linux 设备，通过不同的个人账号登录
  • 配置的 pipeline 中有调用 python 脚本，后者里面有拉取多个工程仓库代码
  • 官方操作指导文档，亦有小问题，混用 install gitlab-runner 与启动方式

账户差异导致的问题

代码仓无法下载、访问

如果是手动登录 Linux 机器，进行 git 克隆代码仓库，无法下载，出现如下报错，肯定第一时间就知道是没权限等原因，一般都去排查一下 ssh 秘钥有没配置、是否需要更新。

cmd 复制代码 
git clone git@qcp-gitlab.xxx.xyz:abc/abcdef.git
Cloning into 'abcdef'...
GitLab: The project you were looking for could not be found.
fatal: Could not read from remote repository.
Please make sure you have the correct access rights

但是，如果是通过 gitlab-runner、jenkins agent 等工具在机器上执行拉取仓库出现同样的问题时，可能让人会有疑惑。

ssh 秘钥对应不同的 gitlab 账户，root账户使用的SSH密钥(/root/.ssh/id_rsa.pub)和普通用户的SSH密钥对应的是不同的GitLab账户，而root对应的GitLab账户可能没有该仓库的访问权限。

需要注意的是：在普通用户下配置了自己账户的秘钥，而 root 对应的秘钥也需要配置，同时将用户账号加入到项目成员中。

检查 ssh 连接的 gitlab 的用户身份：

cmd 复制代码 
# root 账户下，显示的是机器定制配置的名字
ssh -T git@qcp-gitlab.xxxx.xyz
Welcome to GitLab,  qcpmaster!

# autotest 账户下，会显示用户的名字
ssh -T git@qcp-gitlab.xxxx.xyz
Welcome to GitLab, 周星星!

目录或文件无法访问

在安装 gitlab-runner 时，有的指导文档会使用 --user=gitlab-runner 参数，指定用户来安装，导致后续启动、执行时也是该用户。

该用户可能没有权限访问很多目录，导致在执行 pipeline 遇到创建目录或者文件时，就会提示 no permission。

解决办法

对于代码仓无法下载

  • 如果是账户没有配置秘钥，那么只要切换到对应用户环境，生成公钥，配置到 gitlab 上
  • 在 gitlab 项目中，给执行环境的用户（比如这里的qcpmaster）添加为成员（至少 Developer 或 Reporter），让用户可以访问该仓库代码

对于目录或文件无法访问

  • 给 gitlab-runner 用户必要的权限，比如特定目录访问权限（pipeline中配置的）

    bash 复制代码 
    # root账户下，或者加上sudo执行
chown -R gitlab-runner:gitlab-runner /home/tools/gitlab-runner
chmod -R 755 /home/tools/gitlab-runner

  • 确保 gitlab 构建缓存目录有权限

    bash 复制代码 
    sudo chown -R gitlab-runner:gitlab-runner /home/gitlab-runner

启动方式导致的问题

重要提示 ：不要混用 gitlab-runner start/stop 和 systemctl 命令！

学到了

bash 复制代码 
# ✅ 正确方式（通过 systemd 管理）
sudo systemctl start gitlab-runner
sudo systemctl stop gitlab-runner
sudo systemctl restart gitlab-runner
sudo systemctl status gitlab-runner

# ❌ 不好的方式（直接命令，不通过 systemd）
gitlab-runner start
gitlab-runner stop

问题复述

runner 明明已经启动了，但是 gitlab 上的 job 一直处于 pending 状态，于是去查看 runner 状态，发现服务启动失败了：

bash 复制代码 
(base) [root@dgvxl2905 tools]# gitlab-runner status
Runtime platform                                    arch=amd64 os=linux pid=26119 revision=139a0ac0 version=18.4.0
gitlab-runner: Service is running
(base) [root@dgvxl2905 tools]# gitlab-runner stop
Runtime platform                                    arch=amd64 os=linux pid=26150 revision=139a0ac0 version=18.4.0
(base) [root@dgvxl2905 tools]# gitlab-runner start
Runtime platform                                    arch=amd64 os=linux pid=26205 revision=139a0ac0 version=18.4.0
(base) [root@dgvxl2905 tools]#
(base) [root@dgvxl2905 tools]# systemctl status gitlab-runner
● gitlab-runner.service - GitLab Runner
   Loaded: loaded (/etc/systemd/system/gitlab-runner.service; enabled; vendor preset: disabled)
   Active: activating (auto-restart) (Result: exit-code) since Tue 2025-xx-xx 16:53:57 CST; 5s ago
  Process: 26218 ExecStart=/usr/local/bin/gitlab-runner run --config /etc/gitlab-runner/config.toml --working-directory /home/tools/gitlab-runner --service gitlab-runner --user gitlab-runner (code=exited, status=1/FAILURE)
 Main PID: 26218 (code=exited, status=1/FAILURE)

原因：多次启动了 gitlab-runner 服务，配置文件混乱，有的 runner 已经从 gitlab 页面上删除，但是机器上还保留着安装时对应的 toml 配置文件，导致每次使用 gitlab-runner start 启动都是旧的配置，看起来是在 running，但服务又 failed。

解决

bash 复制代码 
# 以下均在 root 下执行，不再添加 sudo 了
# 1. 停止所有进程
pkill -9 gitlab-runner
# 2. 检查并修复用户
id gitlab-runner || useradd --system --shell /bin/bash --home /home/gitlab-runner gitlab-runner
# 3. 修复工作目录，防止文件夹不存在
mkdir -p /home/tools/gitlab-runner
chown -R gitlab-runner:gitlab-runner /home/tools/gitlab-runner
# 使用 systemd 启动服务，而不是直接命令
gitlab-runner verify
systemctl daemon-reload
systemctl start gitlab-runner
systemctl status gitlab-runner

小结

提炼的安装、启动方式

bash 复制代码 
# 下载、赋予执行权限
curl -L --output /usr/local/bin/gitlab-runner "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-linux-amd64"
chmod +x /usr/local/bin/gitlab-runner
# 创建用户
useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash
# 这一步创建了 systemd 服务！此时 systemd 知道了 gitlab-runner 服务的存在
gitlab-runner install --user=gitlab-runner --working-directory=/home/tools/gitlab-runner
# 此时最好不要用 gitlab-runner start 启动，而是用 systemd
systemctl start gitlab-runner

gitlab-runner 用户

报错

bash 复制代码 
$ set -euo pipefail # collapsed multi-line command
error: could not lock config file /home/gitlab-runner/.gitconfig: No such file or directory，
bash 复制代码 
mkdir: cannot create directory '/home/autotest': Permission denied

原因

  • Git 配置文件权限问题。GitLab Runner 在执行任务时，以 gitlab-runner 用户运行，但该用户的家目录配置不完整
  • .gitlab-ci.yml 配置上，gitlab-runner 用户没有权限创建或访问 /home/autotest 目录及其子目录。

解决

创建并修复 gitlab-runner 家目录。

bash 复制代码 
sudo mkdir -p /home/gitlab-runner
sudo chown -R gitlab-runner:gitlab-runner /home/gitlab-runner
sudo chmod 755 /home/gitlab-runner
sudo -u gitlab-runner touch /home/gitlab-runner/.gitconfig
sudo chmod 644 /home/gitlab-runner/.gitconfig

yml 中使用 CI 环境

yaml 复制代码 
variables:
  # 使用 CI 工作目录或共享目录
  TARGET_BUILD_DIR: "${CI_PROJECT_DIR}/doc/build"
  LOG_DIR: "${CI_PROJECT_DIR}/logs"

给 gitlab-runner 用户访问权限（如果必须使用 /home/autotest 路径）

bash 复制代码 
# 方法 A：将 gitlab-runner 加入 autotest 组
sudo usermod -aG autotest gitlab-runner

# 方法 B: 设置目录权限，允许组成员访问
sudo chmod 755 /home/autotest
sudo chmod -R 755 /home/autotest/tools
sudo chmod -R 755 /home/autotest/vlt

# 重启 gitlab-runner 使组权限生效
sudo systemctl restart gitlab-runner

755 的含义:

  • 7 (owner): 读+写+执行
  • 5 (group): 读+执行
  • 5 (others ): 读+执行 ← 这是关键，任何用户 (包括 gitlab-runner)都可以读取和访问这些目录，不需要加入任何组

代码仓库权限

错误信息：

  • Host key verification failed - 缺少 known_hosts
  • Could not read from remote repository - 缺少 SSH 密钥或权限

问题分析

  1. 手动可以克隆：用的是 root 或 autotest 用户，有配置好的 SSH 密钥
  2. Pipeline 失败：gitlab-runner 用户没有 SSH 密钥，也没有 GitLab 服务器的 host key

最佳解决：

直接切换到 gitlab-runner 用户，ssh-keygen 生成并配置秘钥到仓库。

gitlab runner 日志

掌握查看日志，可以排查出很多问题。

对于通过 systemd 管理的 Runner

bash 复制代码 
# 查看实时日志
sudo journalctl -u gitlab-runner -f
# 查看最近的日志
sudo journalctl -u gitlab-runner -n 100
# 查看指定时间范围的日志
sudo journalctl -u gitlab-runner --since "2024-09-30 10:00:00" --until "2024-09-30 12:00:00"
# 查看今天的日志
sudo journalctl -u gitlab-runner --since today
# 只看错误级别日志
sudo journalctl -u gitlab-runner -p err

检查 Runner 状态

bash 复制代码 
# 查看 Runner 服务状态
sudo systemctl status gitlab-runner

# 查看 Runner 版本和配置
sudo gitlab-runner --version
sudo gitlab-runner verify
# 查看配置文件内容、文件权限
cat /etc/gitlab-runner/config.toml
ls -la /etc/gitlab-runner/config.toml

# 列出所有注册的 Runner
sudo gitlab-runner list
相关推荐
明月心9521 天前
git remote add 用法
gitlab
only_Klein1 天前
jenkins流水线报错：Connection reset by peer
ci/cd·kubernetes·gitlab·jenkins·ssl
梁萌2 天前
docker部署gitlab和gitlab runner
docker·eureka·gitlab
johnnyAndCode2 天前
Idea 设置GitLab时使用账密，而不是token的配置方法
gitlab·idea
天外飞雨2 天前
Gitlab使用
gitlab
BUTCHER53 天前
GitLab SSH 密钥配置
运维·ssh·gitlab
明月心9523 天前
GitLab使用
gitlab
明月心9524 天前
gitlab pull requets
gitlab
BUTCHER54 天前
GitLab基本设置
gitlab
张小凡vip4 天前
Kubernetes---gitlab的ci/cd发布基于k8s的项目示例参考
ci/cd·kubernetes·gitlab
热门推荐
01GitHub 镜像站点02Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services03使用 1panel面板 部署 php网站04OpenClaw Chrome扩展使用教程 - 浏览器中继控制05Vue-skills的中文文档06Linux下V2Ray安装配置指南07让 Trae IDE 智能体 “读懂”文档 Excel+PDF+DOCX ：mcp-documents-reader 工具使用指南08从零搭建一个 PHP 登录注册系统（含完整源码）09UV安装并设置国内源10一文了解国产算子编程语言 TileLang，TileLang 对国产开源生态的影响与启示