GitLab Runner 安装：注册 Runner、配置 Executor

安装 GitLab Runner，说白了就是在你的机器上养一个“跑腿小弟”。 这个小弟专门接收 GitLab 发来的 CI 任务，然后按照你写的 .gitlab-ci.yml 去执行。 我个人习惯把 Runner 装在一台单独的 Linux 机器上，不跟 GitLab 服务挤在一起，省得互相抢资源。

Runner 是个啥？

你想想看，GitLab 本身只负责代码托管和触发流水线，真正干活的是 Runner。 Runner 可以跑在物理机、虚拟机、Docker 容器里，甚至 Kubernetes pod 里头。 每个 Runner 有自己唯一的 ，注册到 GitLab 之后，GitLab 就认得它了。

核心概念：Runner = 执行代理；Executor = 任务运行环境。

Executor 决定了你的 CI job 跑在 Shell 里、Docker 里、还是 Kubernetes 里。

第一步：安装 Runner 二进制包

我在项目中遇到过好几次安装失败的情况，大多是因为源没配好。 下面以 Ubuntu/Debian 为例，把官方仓库地址加进去，然后直接 apt 安装：

# 添加 GitLab 官方仓库
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash

# 安装
sudo apt-get install -y gitlab-runner

装上之后，验证一下版本：

gitlab-runner --version

如果看到类似 Version: 16.11.0 的输出，说明装好了。 嗯，这里要注意：不同 GitLab 版本对 Runner 版本有兼容性要求，尽量保持对齐。 我吃过亏：GitLab 16 配了 Runner 15，注册时一直报 错误，后来升级才解决。

第二步：注册 Runner

注册就是把 Runner 和你的 GitLab 项目关联起来。 你需要三样东西：GitLab 实例的 URL、项目的注册 、给 Runner 起个名字。 从哪里拿？进项目 -> Settings -> CI/CD -> Runners -> 展开，就能看到。

我个人很少用交互式注册，太慢了。直接一行命令搞定：

sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.example.com" \
  --registration- "你的项目" \
  --executor "shell" \
  --description "my-shell-runner"

注册成功后，Runner 的信息会写入 /etc/gitlab-runner/config.toml。 你可以用 sudo cat /etc/gitlab-runner/config.toml 看看，里边长这样：

[[runners]]
  name = "my-shell-runner"
  url = "https://gitlab.example.com"
   = "xxx"
  executor = "shell"
  [runners.custom_build_dir]
  [runners.cache]
    [runners.cache.s3]
    [runners.cache.gcs]
    [runners.cache.azure]

注意： 是敏感信息，千万别把 config.toml 提交到 Git 仓库里。 我见过有人把整个 /etc/gitlab-runner 目录打成压缩包发到群里… 嗯，你懂的。

第三步：配置 Executor – Shell

Shell executor 是最直接的：Runner 直接在宿主机上执行 sh 或 bash 命令。 说白了，你的 CI job 里写的 script: 部分，就是直接在机器上敲命令。

优点：简单，不需要额外环境。缺点：污染宿主机，跑一次 CI 可能会留下文件或进程。 适用场景：快速验证、单机小项目、你有权随便造机器的时候。

配置完 Shell executor 后，记得把 gitlab-runner 用户加到 sudo 组里，否则很多命令跑不了：

sudo usermod -aG sudo gitlab-runner

我曾经因为忘了这步，导致流水线里 apt update 和 systemctl restart 全都报错，排查了好久才发现权限问题。

第四步：配置 Executor – Docker

Docker executor 是生产环境的首选。每个 CI job 都会启动一个干净容器，跑完自动销毁，互不干扰。 你想想看，这样就不会出现“上次跑的残留文件把这次单测搞挂”的情况了。

先确保宿主机上已经安装了 Docker 并启动：

sudo apt-get install -y docker.io
sudo systemctl start docker
sudo systemctl enable docker

然后把 gitlab-runner 用户加到 docker 组，否则 Runner 调不了 Docker 命令：

sudo usermod -aG docker gitlab-runner

注册 Docker executor 时，命令稍微加几个参数：

sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.example.com" \
  --registration- "你的项目" \
  --executor "docker" \
  --docker-image "alpine:latest" \
  --description "my-docker-runner"

--docker-image 是默认镜像，如果你的 .gitlab-ci.yml 里没指定 image:，就会用这个。 我个人习惯设成 openjdk:17-jdk-slim，因为课程是 Kotlin 项目，跑测试需要 JDK。

再看一下配置好的 config.toml：

[[runners]]
  name = "my-docker-runner"
  url = "https://gitlab.example.com"
   = "yyy"
  executor = "docker"
  [runners.docker]
    image = "alpine:latest"
    privileged = false
    volumes = ["/cache"]
  [runners.custom_build_dir]
  [runners.cache]

小建议：开发环境可以用 Shell executor 求快，生产环境一定用 Docker executor 求隔离。 Docker executor 的 privileged 模式慎重开，除非你需要在容器里再跑 Docker（Docker in Docker），否则保持 false。

一张图看懂整个流程

下面我把安装 → 注册 → 配置 executor 的路线画了出来，方便你记住关键步骤：

GitLab Runner 安装与注册流程 ① 安装 gitlab-runner 包 ② 注册 获取 + URL ③ 选择 Executor Shell / Docker / 其他 分支 Shell Executor 宿主机直接执行 分支 Docker Executor 容器隔离执行 ④ 开始运行 接收 GitLab CI 任务 提示：配置完 Docker executor 记得将 gitlab-runner 加入 docker 组

Shell vs Docker：如何选？

对比维度 Shell Executor Docker Executor
环境隔离 ❌ 无隔离，污染宿主机 ✅ 每次启动新容器，互不影响
启动速度 快（直接执行） 稍慢（需拉镜像、起容器）
环境一致性 依赖宿主机软件版本 完全由镜像控制，可复现
权限风险 高（runner 用户有 sudo） 低（容器内操作受限）
推荐场景 个人开发机、简单脚本 生产环境、多项目、需要 JDK 等

避坑指南：我曾经在生产环境用了 Shell executor，结果一次 CI job 里执行了 rm -rf / （虽然带了权限判断，但依然心有余悸）。 从此以后，凡是跑正式流水线，我一定用 Docker executor 加非特权模式。 另外，Docker executor 里如果依赖 Docker in Docker，记得挂载 /var/run/docker.sock，但这会降低隔离性，权衡着用。

注册后的验证

注册完别急着走，花一分钟验证一下：

  1. 在 GitLab 项目页面看 Settings → CI/CD → Runners，确认 Runner 状态是 绿色（active）。
  2. 手动触发一个简单 pipeline，比如只打印 echo "Hello Runner"，看能不能跑通。
  3. 跑完后点进 job 日志，确认 executor 是你配的那个（Shell 日志会显示 Running with gitlab-runner 16.x.x (xxx) on my-shell-runner）。

我曾经遇到过一次 Runner 显示 红色（not connected），排查发现是防火墙把 Runner 到 GitLab 的 443 端口堵了。 解决办法：在 Runner 机器上 telnet gitlab.example.com 443 测试连通性，不行就加 iptables 规则或调整安全组。

小技巧：如果想查看所有已注册的 Runner 信息，可以用 sudo gitlab-runner list 命令。 这个命令会列出名字、状态、executor 类型，非常直观。

卸载 Runner（万一用不着了）

要是哪天想重装或者换台机器，记得先注销再卸载：

# 注销（需要在 config.toml 里找到对应 runners 的 ）
sudo gitlab-runner unregister --name "my-runner-name"

# 卸载二进制
sudo apt-get remove --purge gitlab-runner

注销后 GitLab 那边会标记 Runner 为离线，不会残留无用记录。 我习惯在每次重装前先 unregister，否则项目里会堆积一堆“已断连”的 Runner，看着闹心。

到这一步，你的 GitLab Runner 已经装好、注册成功，并且选好了 executor。 接下来就可以用它来跑 Kotlin 回归测试了——不过那是后面章节的事，我们先把基础打扎实。

← 上一章 📖 返回目录 下一章 →