当前位置： 首页 > news >正文

实用指南：gitlab-runner 再次实践中理解和学习

news 2025/10/4 19:20:19

实用指南：gitlab-runner 再次实践中理解和学习

文章目录

    • 背景
    • 账户差异导致的问题
    • 启动方式导致的问题
    • gitlab-runner 用户
    • 代码仓库权限
    • gitlab runner 日志

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

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

背景

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

账户差异导致的问题

代码仓无法下载、访问

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

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 的用户身份：

# 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中配置的）

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

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

    sudo chown -R gitlab-runner:gitlab-runner /home/gitlab-runner

启动方式导致的问题

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

学到了

# ✅ 正确方式（通过 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 状态，发现服务启动失败了：

(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。

解决

# 以下均在 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

小结

提炼的安装、启动方式

# 下载、赋予执行权限
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 用户

报错

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

原因

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

解决

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

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 环境

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

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

# 方法 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

# 查看实时日志
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 状态

# 查看 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
http://www.hskmm.com/?act=detail&tid=24396

相关文章：

  • 2025年7月28日当周关键漏洞汇总分析
  • C# 与 C/C++ 互操作
  • 【自然语言处理】文本规范化知识点梳理与习题总结 - 教程
  • 邮票收集问题正推证明
  • 2025多校冲刺CSP模拟赛2 2025.10.4 模拟炸
  • 算法乱谈
  • 2025 年 9 月习题集
  • C# 代码规范
  • 实用指南：babelfish for postgresql 分析--todo
  • NFC 贴卡自动拨打微信视频电话
  • 10.4
  • 实用指南：d-分离：图模型中的条件独立性判定准则
  • [MCP] 监听资源更新
  • [RAG] 基础知识
  • CF1408F Two Different
  • 数据结构 - 字典树 Trie
  • 激活函数实现
  • 漏洞赏金入门指南：从零开始的实战方法论
  • PMON failed to acquire latch 的报错及sqlplus / as sysdba 无法连接 - 详解
  • 2025CSP-S模拟赛58 比赛总结
  • 精读C++设计模式20 —— 结构型设计模式：桥接模式 - 详解
  • 用纯.NET开发并制作一个智能桌面机器人（六）：使用.NET开发一个跨平台功能完善的小智AI客户端
  • 2025/10/4 总结
  • Qt处理Windows平板上摄像头
  • 你必须知道的TCP和UDP核心区别，快速搞懂这两大协议！
  • [swift 外部干涉法 extension]
  • 2025国庆Day3
  • 量子迁移计划启动：应对未来密码学挑战
  • HPE SPP 2025.09.00.00 - HPE 服务器固件、驱动程序和系统软件包
  • 详细介绍：Linux字符设备驱动开发全攻略