Runner 安装、注册与配置

架构

Runner 是独立于 GitLab 服务端的 agent，领取 Job 并执行
一个 Runner 进程可管理多个 runner 实例（config.toml 中多个 runners）
作用域：instance（shared，所有项目可用）/ group / project
匹配规则：Job 的 tags 必须是 Runner tags 的子集才会被分配；未声明 tags 的 Job 只分配给不带 tag 的 Runner

Executor 选型

Executor	场景
`shell`	最简单，宿主机直接执行；环境靠手工维护，适合固定构建机
`docker`	主流选择，每 Job 起容器，`image` 决定环境，隔离好
`kubernetes`	Job 以 Pod 形式跑在 K8s 集群，弹性好，适合大规模
`custom` / `virtual-machine`	特殊硬件或虚机场景

安装

# Debian/Ubuntu
curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash
sudo apt-get install gitlab-runner
 
# RHEL/CentOS
curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.rpm.sh | sudo bash
sudo yum install gitlab-runner
 
# 用 Docker 跑 Runner 自身（挂载 docker.sock 供 docker executor 用）
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

注册（新版 authentication token 流程）

GitLab 16.0 起废弃 registration token，改为在 UI 创建 Runner、获取 glrt- 开头的 authentication token：

UI：Settings → CI/CD → Runners → New project/group runner，设置 tags、是否接受无 tag Job、保护状态等，创建后复制 token
主机上注册：

# 交互式（逐项确认 executor、image 等）
gitlab-runner register --url https://gitlab.example.com --token glrt-xxxx
 
# 非交互（批量部署常用）
gitlab-runner register --non-interactive \
  --url https://gitlab.example.com \
  --token glrt-xxxx \
  --executor docker \
  --docker-image alpine:latest \
  --description "docker-runner-01"

启动：

sudo gitlab-runner run                          # 前台运行，调试用
sudo systemctl enable --now gitlab-runner       # systemd 托管

tags、作用域等元信息现在主要在 UI 侧维护；注册完成后 UI 能看到 Runner 上线（绿色圆点）。

config.toml 关键配置

concurrent = 4          # 全局并发 Job 数上限（所有 runner 实例共享）
check_interval = 3
 
[[runners]]
  name = "docker-runner-01"
  url = "https://gitlab.example.com"
  token = "glrt-..."
  executor = "docker"
  [runners.docker]
    image = "alpine:latest"
    privileged = false                 # DinD 场景需要 true
    volumes = ["/cache"]
    pull_policy = ["if-not-present"]   # 减少镜像拉取延迟
    shm_size = 536870912
  [runners.cache]
    Type = "s3"                        # 多机共享缓存用 S3/MinIO
    Path = "gitlab-cache"
    Shared = true

[runners.kubernetes]：配置 namespace、cpu/memory requests/limits、service_account、volumes
修改配置后 sudo gitlab-runner restart 生效

常用运维命令

gitlab-runner list                        # 列出本机 runner
gitlab-runner verify                      # 校验与 GitLab 的注册状态
gitlab-runner verify --delete             # 清理已失效的注册
gitlab-runner unregister --token glrt-xxx # 注销
gitlab-runner --debug run                 # debug 级日志排障
sudo gitlab-runner restart
journalctl -u gitlab-runner -f            # 查看服务日志

常见坑

“This job is stuck, because the project doesn’t have any runners online”：Job tags 与 Runner tags 不匹配，或 Runner 离线、并发已满
缓存/产物在多机间不生效：local cache 只在同一台机器有效，多 Runner 必须配 S3/MinIO 共享后端
Job 镜像拉取失败：docker executor 由 Runner 进程拉镜像，私有仓库需在 Runner 主机先 docker login；Job 内的 docker login 只影响 script 里自己起的 docker 命令
docker.sock 权限：容器化部署 Runner 时忘记挂载 /var/run/docker.sock 会导致 docker executor 报错

弹性伸缩

固定主机 + docker executor 适合中小规模
大规模用 autoscaling runner manager（GitLab 17.x 新一代方案，取代已废弃的 docker-machine），按需创建云 VM 实例
K8s 场景直接用 kubernetes executor，或 GitLab Runner Helm Chart（支持 HPA）

多项目共享 Runner

Runner 分三级作用域，决定「几个项目能用」：

作用域	创建位置	适用范围
Project runner	项目 → Settings → CI/CD → Runners	仅该项目
Group runner	Group → Settings → CI/CD → Runners	组内全部项目（含子组）
Instance（shared）runner	Admin 后台	全实例所有项目

关键点：token 与创建时选定的作用域绑定。glrt- token 从哪个入口创建，runner 就服务于哪个范围；project runner 的 token 无法再授权给其他项目。

方案选择：

两个项目同组 → 建 group runner，一个 token 全部搞定（推荐）
不同组且无管理员权限 → 注册两个 project runner（见下）
有管理员权限 → 建 instance shared runner

K8s 上注册两个 project runner

一个 gitlab-runner 进程可承载多个 runner 实例（config.toml 中多个 runners 段），K8s 上两种做法：

方式一：两个 Helm release（最简单，互不影响）

helm repo add gitlab https://charts.gitlab.io
helm install runner-proj-a gitlab/gitlab-runner -n gitlab-runner \
  --set gitlabUrl=https://gitlab.example.com --set runnerToken=glrt-项目A的token
helm install runner-proj-b gitlab/gitlab-runner -n gitlab-runner \
  --set gitlabUrl=https://gitlab.example.com --set runnerToken=glrt-项目B的token

方式二：单 Deployment + 预置 config.toml

把两个 runners 段直接写进 config.toml（各带自己的 token），存为 Secret，Helm 用 runners.secret 挂载并跳过 register：

concurrent = 4
 
[[runners]]
  name = "proj-a"
  url = "https://gitlab.example.com"
  token = "glrt-项目A的token"
  executor = "kubernetes"
 
[[runners]]
  name = "proj-b"
  url = "https://gitlab.example.com"
  token = "glrt-项目B的token"
  executor = "kubernetes"

group runner 场景下 runners.config 里只需一个 runners，concurrent 与 kubernetes executor 参数（namespace、cpu/memory requests、volumes）照常配置。无 tag 的 runner 会被两个项目的无 tag Job 共同消费，注意 concurrent 容量规划；需要隔离时给 runner 打 tag，Job 侧用 tags 路由。

zhaoweiguo 的知识库

目录

GitLab Runner 安装、注册与配置