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

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

news 2025/10/3 5:28:24

文章目录

    • 背景
    • 账户差异导致的问题
    • 启动方式导致的问题
    • 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 RunnerLoaded: 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 agoProcess: 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.dtcms.com/a/434250.html

相关文章：

  • C++之stack等容器适配器（上）实战篇
  • JavaWeb零基础学习Day1——HTMLCSS
  • Starting again-01
  • 如何做网站链接使用朝阳seo建站
  • Nivo 用React打造精美数据可视化的开源利器
  • 【iOS安全】iPhone X iOS 16.7.11 (20H360) Palera1n MacOS版 越狱教程
  • 【连载4】数据库热点更新场景调优策略
  • 深入解析HarmonyOS ArkTS：从语法特性到实战应用
  • 小杰深度学习（five）——正则化、神经网络的过拟合解决方案
  • 网页网站开发大概多少钱网站设计公司 深圳龙华
  • 门户网站是什么意思?网站建设哈尔滨app开发2
  • 《吃透 C++ vector：从基础使用到核心接口实战指南》
  • wordpress上传到哪里什么网站利于优化
  • [Web网页] 零基础入门 HTML
  • Nimble：让SwiftObjective-C测试变得更优雅的匹配库
  • HTML——1px问题
  • 【C++项目】基于微服务的即使通信系统
  • wordpress企业站模板建协官网
  • 【办公类-115-04】20250920职称资料上传03——压缩课题结题报告PDF的大小（控制在200MB以内）
  • Python - 100天从新手到大师：第二十七天Python操作PDF文件
  • 做网站一般长宽多少如何线上推广引流
  • C++20 协程：在 AI 推理引擎中的深度应用
  • 如何做游戏推广seo整站优化
  • CompLLM 来了：长文本 QA 效率革命，线性复杂度 + 缓存复用，推理速度与效果双丰收
  • 嵌入式开发中用于调试的技术Semihosting
  • 企业营销型网站建设哪家好手机网站制作 尺寸
  • Python 3 与 MongoDB 的深入探索
  • toLua[五] Examples 04_AccessingLuaVariables分析
  • 云原生时代的数据流高速公路：深入解剖Apache Pulsar的架构设计哲学
  • 在鸿蒙NEXT中使用WebSocket实现实时网络通信