GitLab Runner 详解：执行 CI/CD 流水线的引擎

GitLab Runner 详解：执行 CI/CD 流水线的引擎

在 GitLab 里写好 .gitlab-ci.yml 只是定义了流水线，真正把每个 job 跑起来的，是另一个角色——GitLab Runner。它是开源仓库 gitlab-org/gitlab-runner 提供的 Go 单二进制应用，Go 语言编写、无任何语言运行时依赖，装在独立机器上连接 GitLab 拉取并执行任务，支持 Linux、macOS、Windows、FreeBSD、z/OS 及 Docker、Kubernetes 等几乎所有执行环境。本文从工作原理、执行器、安装注册到配置实践，完整拆解。

1、项目概述

GitLab Runner 是与 GitLab CI/CD 配套的任务执行应用：开发者 push 代码后，GitLab 按流水线定义派发 job，Runner 连接 GitLab 领取任务、在计算基础设施上执行、回传日志与结果。官方明确建议出于安全与性能考虑，Runner 应安装在**独立于 GitLab 实例的机器**上。

基本形态与生态：

        - 形态：Go 编写的单个二进制，无其他依赖，可装成系统服务

        - 部署选项：GitLab 托管 Runner（SaaS）与自管 Runner（全权掌控）

        - 版本约定：Runner 的 major.minor 应与 GitLab 主次版本保持同步

        - 协议为 MIT；功能层覆盖 Free、Premium、Ultimate 全部层级

2、四大核心能力

Runner 的能力可以归成四根支柱，覆盖 CI/CD 执行环节的主要需求。

四根支柱：

        - 并发执行：单机多 job 并发，可按 token 限制并发数，多 token 对接多实例

        - 多样执行环境：本地 Shell、Docker 容器、SSH 远程、Docker 自动扩缩容

        - 环境定制：Shell 类型支持 Bash、PowerShell Core、Windows PowerShell

        - 可观测与运维：内嵌 Prometheus 指标服务、Referee 上报 job 数据、免重启热加载配置

能力要点：

1. 单二进制即完整应用：凡是能跑 Docker 的地方就能跑 Runner

2. 配置自动重载：改 config.toml 无需重启服务

3. Docker 容器缓存加速重复构建

3、执行流程与关键概念

Runner 与 GitLab 的交互分"注册"与"任务循环"两个阶段，官方文档用时序图描述，其中涉及两类 token。

执行流程：

1. 注册：Runner 携带 registration_token 调 POST /api/v4/runners，换取 runner_token

2. 领任务：循环调 POST /api/v4/jobs/request，GitLab 下发带 job_token 的任务载荷

3. 执行：Executor 用 job_token 克隆源码、下载 artifacts，执行 job 脚本

4. 回传：输出与状态用 job_token 回写 GitLab，循环往复

关键概念：

        - Runner：一个可执行任务的配置实例，config.toml 中一个 [[runner]] 段

        - Runner manager：读 config.toml 并并发运行所有 runner 配置与 job 的进程

        - Executor：执行 job 的方式（Shell、Docker、Kubernetes 等）

        - Tags：Runner 上的标签，决定哪些 job 会派给它执行

        - Machine ID：自动生成的唯一持久标识，多机同配置时 UI 分组、job 分流

4、安装：全平台覆盖

安装方式按操作系统与容器环境两大类组织，详见 官方安装文档。

# Linux：官方仓库 + 包管理器（推荐）
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
sudo apt install gitlab-runner

# macOS：用户模式服务（Apple Silicon / Intel x86-64）
brew install gitlab-runner

# Docker：容器化运行 Runner 本体
docker run -d --name gitlab-runner --restart always \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  -v /var/run/docker.sock:/var/run/docker.sock \
  gitlab/gitlab-runner:latest

# Kubernetes：Helm Chart / GitLab agent / Operator 三选一

安装要点：

1. 生产建议装在独立机器，与 GitLab 实例分离

2. Docker 方式需挂载 docker.sock 以支持 docker executor

3. K8s 场景优先 Helm Chart，Operator 适合需要 CRD 管理的团队

4. 另有 FreeBSD、z/OS 手动安装与 Bleeding edge 开发版

5、注册与配置实践

安装后必须注册到 GitLab 实例才开始干活，核心是 config.toml。

# 注册（交互式填 URL 与 token）
sudo gitlab-runner register

# 非交互式一条命令
sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.example.com/" \
  --registration-token "PROJECT_REGISTRATION_TOKEN" \
  --executor "docker" \
  --docker-image "alpine:latest" \
  --description "docker-runner"

# config.toml 关键段
concurrent = 4          # 全局并发 job 数
[[runners]]
  name = "docker-runner"
  executor = "docker"
  [runners.docker]
    image = "alpine:latest"
    privileged = false

配置要点：

1. concurrent 控制全局并发，单个 runner 还可再设 limit

2. tags 与 .gitlab-ci.yml 中 job 的 tags 匹配才被派发

3. 修改配置文件自动热加载，无需重启服务

4. 多个 [[runners]] 段可在一个 manager 里混跑多种 executor

6、典型应用场景

从个人项目到企业级 CI，Runner 的选型路径很清晰。

常见场景：

        - 开源/个人项目：直接用 GitLab.com 托管 Runner，零维护

        - 企业内网构建：自管 Runner + docker executor，环境统一可控

        - 弹性伸缩：Docker + 云上自动扩缩容，按需起停构建机

        - 云原生团队：Kubernetes Helm Chart 部署，Pod 即构建环境

        - Windows 构建：PowerShell executor 跑 .NET、桌面应用测试

运维提醒：

1. 版本同步：Runner major.minor 与 GitLab 保持一致，避免新特性失效

2. 仓库在 GitLab.com 的自管 Runner 记得持续更新版本

3. Runner 机器就是代码执行环境，务必隔离并限权

7、定位对比：CI 执行器三选一

把 GitLab Runner、GitHub Actions Runner 与 Jenkins Agent 放在一张桌上，各自的位置清晰起来。

三者对比：

        - GitLab Runner：GitLab 原生，Go 单二进制，executor 丰富，配置热加载

        - GitHub Actions Runner：GitHub 原生 self-hosted 方案，生态绑定 Actions 语法

        - Jenkins Agent：老牌 CI 的执行节点，插件海量但运维面更重

选型建议：

1. 代码托管在 GitLab → GitLab Runner，原生集成无可替代

2. 仓库在 GitHub、要自托管算力 → Actions self-hosted runner

3. 已有 Jenkins 资产与复杂流水线拓扑 → 保留 Agent 渐进迁移

4. 组合玩法：GitLab Runner 主力构建，特殊硬件节点用 tags 分流专用 runner

8、总结

GitLab Runner 是 GitLab CI/CD 的执行引擎（MIT 协议）：Go 单二进制零依赖，以 registration/runner/job 三类 token 完成注册与任务循环；executor 覆盖 Shell、Docker、Kubernetes、SSH 与自动扩缩容，concurrent 与 limit 精细控并发，配置热加载、内嵌 Prometheus 指标；安装矩阵横跨 Linux、macOS、Windows、FreeBSD、z/OS 与容器环境，版本与 GitLab 主次号保持同步即可长期稳定。

运维要点：executor 首选 docker 保证环境可复现；tags 规划先行，构建、测试、部署分层派发；生产机常开 Prometheus 抓取 Runner 指标，容量不足再上自动扩缩容。Runner 机器即代码执行环境，隔离与限权是安全底线。