GitLab Runner配置：从安装到跑通第一条流水线

GitLab Runner 配置的核心目标只有一个：让 GitLab 上的项目能把流水线任务派发到一台机器上执行。
只要 Runner 注册成功、标签对得上、执行器可用，.gitlab-ci.yml 里的 job 就能跑起来。
下面按安装、注册、改配置、验证四个阶段展开，环境以常见的 Linux 服务器为例。

先确认安装方式和前提条件

GitLab Runner 支持二进制包、Docker、系统包管理器三种安装方式。
如果只是给一台普通 Linux 服务器做构建机，用官方仓库安装最省事；
如果希望构建环境隔离，用 Docker 执行器更合适。

开始前需要准备：

• 一台能访问 GitLab 的 Linux 服务器，建议 2 核 4G 起步，具体取决于构建任务。
• 一个 GitLab 项目或群组，以及有权限创建 Runner 的账号。
• 项目的注册令牌或 Runner 认证令牌，在 GitLab 项目的 Settings > CI/CD > Runners 里获取。
• 服务器上已安装 git、curl，构建项目还需要对应的语言运行环境。

需要区分两种注册方式：旧版使用注册令牌（registration token），较新版本推荐用认证令牌（authentication token）配合 glrt- 前缀。
以你所在 GitLab 实例页面实际显示的为准，不要照搬过时教程。

安装 GitLab Runner

以 Debian/Ubuntu 为例，添加官方仓库并安装：

curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
sudo apt install gitlab-runner

CentOS/RHEL 系用对应的 rpm 脚本，安装完成后检查版本：

gitlab-runner --version

安装后系统会创建 gitlab-runner 用户并注册为服务。
用 systemctl status gitlab-runner 确认服务处于运行状态。

注册 Runner 并绑定到项目

注册是把这台机器和 GitLab 上的某个项目或群组关联起来。
旧版注册命令：

sudo gitlab-runner register

交互过程中会依次询问：

• GitLab 实例地址，例如 https://gitlab.example.com。
• 注册令牌，粘贴页面上复制的 token。
• Runner 描述，自己起一个能识别机器的名字。
• 标签（tags），例如 build、deploy，后续在 .gitlab-ci.yml 里用 tags 匹配。
• 执行器，选 shell 或 docker。

如果使用认证令牌，注册命令改为带上 --token 参数，不再需要 URL 和注册令牌，按当前 GitLab 文档的参数填写即可。
注册成功后，在 GitLab 项目的 Runners 页面能看到这台 Runner 处于在线状态。

修改 config.toml 调整并发和执行器

Runner 的主配置文件在 /etc/gitlab-runner/config.toml。
注册后每个 Runner 会生成一段 [[runners]] 配置。

常见需要调整的项：

concurrent = 4

[[runners]]
  name = "build-runner"
  url = "https://gitlab.example.com"
  executor = "shell"
  [runners.custom_build_dir]
    enabled = true

• concurrent 是全局同时执行的任务数，按服务器 CPU 和内存量力设置，设太大容易把机器打满。
• executor 决定构建在宿主机（shell）还是容器（docker）里跑。
• docker 执行器还需要配置 [runners.docker] 段的镜像和卷。

改完配置后重载服务让改动生效：

sudo gitlab-runner restart

验证流水线是否真的跑通

在项目根目录放一个最简单的 .gitlab-ci.yml：

stages:
  - test

job1:
  stage: test
  tags:
    - build
  script:
    - echo "runner is working"
    - whoami

提交后进入项目的 CI/CD > Pipelines，能看到新流水线。
点进 job 查看日志，如果输出 runner is working 说明 Runner 配置成功。
若任务是 pending 状态一直等待，优先检查 job 的 tags 和 Runner 标签是否完全一致，以及 Runner 是否被设置为“只能运行带标签的任务”。

常见报错和避坑点

任务一直 pending：最常见原因是标签不匹配，或 Runner 被锁定到其他项目。
到 Runners 页面确认状态和标签。

权限错误、无法写入构建目录：shell 执行器默认以 gitlab-runner 用户运行，构建目录权限不足会报错。
检查 /home/gitlab-runner 的属主和权限，必要时调整。

git clone 失败：确认服务器能解析并访问 GitLab 域名，内网实例要检查 DNS 和防火墙规则。

不要用 root 跑 shell 执行器：除非明确知道风险。
默认 gitlab-runner 用户是更稳妥的做法，需要提权时通过 sudoers 精确授权。

config.toml 改错导致服务起不来：
改动前先备份 cp /etc/gitlab-runner/config.toml /etc/gitlab-runner/config.toml.bak，
出问题可快速回滚。

几个容易混淆的问题

Runner 和 Executor 有什么区别？ Runner 是执行代理程序，Executor 是它内部真正运行构建的方式，比如 shell、docker、kubernetes。
同一台机器可以注册多个 Runner，用不同执行器。

项目 Runner 和群组 Runner 怎么选？ 只服务单个项目就用项目 Runner；
多个项目共用构建机，用群组 Runner 更省事，但要注意任务隔离。

改完标签要重新注册吗？ 不一定。
可以在 config.toml 里直接改 tags，或到 GitLab 页面编辑 Runner 信息，改完重启服务即可。

GitLab Runner 配置本身不复杂，卡人的通常是标签匹配、权限和网络连通性这三类问题。
按本文顺序装好、注册、改配置、跑一条最小流水线验证，再逐步加构建内容，出问题时优先看 job 日志里的第一行报错，定位会快很多。