CICD基础 -- GitLab Runner 的安装以及使用-CSDN博客

一、通过官方仓库安装

步骤全部在一台 Ubuntu 上执行：

添加 GitLab Runner 官方仓库：

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

这个脚本会：

导入 GPG key
写入 /etc/apt/sources.list.d/runner_gitlab-runner.list

安装 GitLab Runner：

sudo apt update
sudo apt install gitlab-runner

安装完成后会自动创建：

用户 gitlab-runner
systemd 服务 gitlab-runner.service

启动并设为开机自启：

sudo systemctl enable gitlab-runner
sudo systemctl start gitlab-runner

验证：

gitlab-runner --version
systemctl status gitlab-runner

看到版本号、服务为 active (running) 就 OK 了。

二、使用说明

1. `gitlab-runner register` 本质在做啥？

用一个“Runner 认证 token”把当前这台机器作为 Runner 绑定到某个 GitLab 实例（以及某个作用域：实例/组/项目），并写入 config.toml。

执行完会在（典型 Linux）：

/etc/gitlab-runner/config.toml

里新增一个：

[[runners]]
  name = "xxx"
  url = "https://gitlab.xxx"
  token = "glrt-xxxx"
  executor = "docker"
  ...

后面 GitLab 派 Job 给这个 Runner，全靠这里这堆信息。

所以 register 就是“生成/填充这个 [[runners]] 配置块”的过程。

2. 交互式注册：每一步什么意思、去哪拿值

你执行：

gitlab-runner register

会看到一堆问题（不同版本提示略有变化）：

2.1 GitLab instance URL

提示示例：

Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com/):

填什么？

GitLab.com：https://gitlab.com
自建 GitLab：你的 Web 访问地址，例如 https://gitlab.example.com

怎么确认？

浏览器打开你 GitLab 首页，地址栏的根 URL 就是这个（不要带项目路径）。

2.2 Runner authentication token（新）或 registration token（旧，已废弃中）

现在推荐、并逐步强制使用 Runner authentication token（glrt-xxxx 开头）。老的 registration token 正在废弃。

提示示例：

Please enter the runner authentication token:

这个 token 去哪拿？取决于你想让 Runner 属于哪里：

项目级 Runner（只给单个项目用）：
- 进项目 → Settings → CI/CD → 展开 Runners
- 找 “New project runner” / “Create runner” 流程
- GitLab 会生成一个 glrt-... 的 token 和一条推荐命令
组级 Runner（给整组项目共享）：
- 进 Group → 左侧 CI/CD / Runners（不同版本 UI 名有些变化）
- “New group runner”/“Create runner”，同理拿到 glrt-...
实例级 Runner（Admin 才有）：
- Admin Area → Runners → “New instance runner”

交互式时就把这个 glrt-xxxx 粘进去。

老文档里那种 Please enter the registration token: 是旧模式（项目/组注册 Token），现在官方建议迁移为 UI 创建 Runner → 拿 authentication token → register。

2.3 Description（描述）

提示示例：

Please enter the runner's description:

随便写，建议写出用途和位置，后面好认：

如：docker-runner-01, build-node-1, fpga-ci-runner

在 GitLab UI 的 Runner 列表会看到这一串。

2.4 Tags（tag-list）

提示示例：

Please enter the runner's tags (comma-separated):

用于 Job 选择 Runner。

例子：docker,linux,build
.gitlab-ci.yml 里：

tags: ["docker", "build"]

就会派到有这些 tag 的 Runner。

使用建议：

给不同能力机器打不同标签：aarch64, fpga, windows, high-mem, docker。
如果你只有一个 Runner，也可以简单写一个 docker，方便管理。

2.5 是否可以跑未打 tag 的 Job（run untagged jobs）

提示示例：

Whether to run untagged jobs [true/false]:

true：没有 tags: 的 job 也可以用这个 Runner。
false：只有 tags 匹配的 job 才能用它。

建议：

小团队 or 只有一台 Runner：先选 true，减少困扰。
多 Runner + 分工明确：建议设为 false，强制 job 写 tags，避免乱跑。

2.6 是否锁定到当前项目（locked to current project）

老版本提示类似：

Whether to lock the Runner to current project [true/false]:

现在语义是“这个 Runner 只能被当前作用域使用”。如果你用的是项目级 runner，本来就是给这个项目用的，锁不锁看你需求。

选 true：只能服务这个项目（安全、可控）。
选 false：允许在更大作用域里复用（看你注册的是哪级 Runner）。

2.7 Executor（执行器类型）

提示示例：

Please enter the executor: shell, docker, docker+machine, kubernetes, custom, ...

这是关键选项，决定 Job 在哪儿怎么跑。

常用几个：

docker：推荐。每个 Job 跑在一个容器里，干净、可复现。
shell：直接在宿主机跑脚本。
kubernetes：在 k8s 集群里动态起 Pod。
custom：自己写 executor，暂且略过。

如果选 docker，接下来会问：

Please enter the default Docker image (e.g. ruby:2.7):

填：alpine:3.19，ubuntu:22.04 或你自己的构建镜像。
.gitlab-ci.yml 里可以覆盖，但这里要有个默认。

Docker executor 说明见官方文档。

3. 常用参数 & 非交互式写法

完全可以直接用一条命令把所有东西写死，省掉交互。

3.1 核心参数说明

常用的一些（不同版本略有增减，这里讲实用的）：

gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.example.com" \
  --token "glrt-xxxx" \
  --name "docker-runner-01" \
  --tag-list "docker,linux" \
  --run-untagged="true" \
  --locked="false" \
  --executor "docker" \
  --docker-image "alpine:3.19"

逐个解释：

--non-interactive
- 非交互模式，所有内容用参数给出，适合脚本化、自动部署。
--url
- GitLab 实例 URL，如上。
--token
- Runner authentication token（glrt-...）。
- 从 GitLab UI 创建 Runner 时拿到。([GitLab 文档][1])
--name
- 等价于描述，Runner 在 UI 的显示名字。
--tag-list
- 逗号分隔："docker,linux,build"。
--run-untagged=true|false
- 同上“是否跑 untagged job”。
--locked=true|false
- 是否锁定当前作用域。
- 对项目级 Runner，一般 true/false 看你要不要将来挪用。
--executor
- shell / docker / kubernetes / custom 等。
--docker-image
- 默认使用的镜像，仅在 --executor docker 时有效。

再进阶一点（常用但不是必须）：

--docker-privileged=true
- 若你要在 CI 里 docker build（Docker in Docker），常会用到。
--docker-volumes
- 挂宿主机目录进容器，如缓存目录、Docker socket 等。
--config /path/to/config.toml
- 指定配置文件路径，在 Docker 模式或多 Runner 配置时有用。

3.2 如何从 UI 正确拿到这些值

假设你要一个“项目级 Docker Runner”：

进入项目 → Settings → CI/CD → Runners。
找到 “New project runner” 或类似按钮。
在 UI 里选择：
- 作用域：Project
- 执行环境：Shell / Docker / Kubernetes 等
- 标记：如 docker

GitLab 会给你一段官方推荐命令，比如：

gitlab-runner register \
  --url "https://gitlab.example.com" \
  --token "glrt-xxxx" \
  --executor "docker"

拿这段命令到你那台 CI 服务器上执行即可。

你完全可以基于它加上 --non-interactive、--tag-list 等参数，做成你自己的标准脚本。

4. 一个能直接用的“标准注册脚本模版”

你可以在 CI 节点上放一个类似：

#!/bin/bash
set -e

GITLAB_URL="https://gitlab.example.com"
RUNNER_TOKEN="glrt-xxxx-from-ui"
RUNNER_NAME="docker-runner-01"
RUNNER_TAGS="docker,linux"
DEFAULT_IMAGE="alpine:3.19"

gitlab-runner register \
  --non-interactive \
  --url "${GITLAB_URL}" \
  --token "${RUNNER_TOKEN}" \
  --name "${RUNNER_NAME}" \
  --tag-list "${RUNNER_TAGS}" \
  --run-untagged="true" \
  --locked="false" \
  --executor "docker" \
  --docker-image "${DEFAULT_IMAGE}"

改 3 个位置即可：

GITLAB_URL
RUNNER_TOKEN（从 UI 复制）
根据机器命名 RUNNER_NAME / RUNNER_TAGS

三、反注册销毁废弃的 Runner

1. 先认清你要删的是哪一个 Runner

在 Runner 机器上看：

gitlab-runner list

输出类似：

Listing configured runners                          ConfigFile=/etc/gitlab-runner/config.toml
docker-runner-01             Executor=docker Token=xxxxx URL=https://gitlab.example.com
fpga-runner-01               Executor=shell  Token=yyyyy URL=https://gitlab.example.com

或者直接看配置：

cat /etc/gitlab-runner/config.toml

里面每个 [[runners]] 就是一个 Runner。

记住要干掉的：

name（描述）
url
token

这三个是后面执行 unregister 的关键。

2. 标准反注册方式

方式 2.1：按 Runner 名称反注册

如果你当初 register 时设置了有区分度的 --name：

gitlab-runner unregister --name "docker-runner-01"

效果：

从 config.toml 删除对应 [[runners]] 配置。
通知 GitLab 把这个 Runner 标记为已删除（不再派 Job）。

适用：同机多个 Runner，用 name 最直观。

方式 2.2：按 URL + Token 精确反注册

更底层一点，也是最“保险精确”的方式：

gitlab-runner unregister \
  --url "https://gitlab.example.com" \
  --token "glrt-xxxx"

注意这个 token 是 Runner 的 注册/认证 token，不是项目的访问 token。

从哪拿？

config.toml 里对应 Runner 的 token = "glrt-xxxx"。
或 GitLab Web UI 里对应 Runner 详情页。

适用场景：

名字不唯一、改过 name 的；
或你就是想手起刀落，明确干掉某个 token 对应的 Runner。

方式 2.3：一口气清空所有 Runner

gitlab-runner unregister --all-runners

直接把当前 config.toml 里配置的所有 Runner 都反注册掉。
适用于：这台机器退役 / 整机迁移前清理。

四、GitLab Runner 的 docker 配置字段说明

1. 整体模型：Docker executor 到底干了啥

当 Runner=docker executor 时，每个 Job 大致流程：

prepare：起 helper 容器、服务容器（services），准备工作目录。
pre-job：拉代码、恢复 cache。
job：用指定 image 起一个容器，把你的 script 丢进去执行。
post-job：上传 artifacts、写 cache。

用哪些镜像、挂哪些卷、是否 privileged、如何拉镜像，全部由：

.gitlab-ci.yml 的 image: / services: / variables:
config.toml 的 [runners.docker] 字段

共同决定。

2. 标准 `config.toml` 示例（Docker 版）

一个精简但规范的模板，后面按字段拆：

concurrent = 4

[[runners]]
  name = "sm-driver-runner-51"
  url = "https://gitlab.example.com"
  token = "glrt-xxxx"
  executor = "docker"
  request_concurrency = 2

  [runners.docker]
    image = "ubuntu:22.04"
    pull_policy = ["if-not-present"]
    privileged = false
    volumes = ["/path/to/host/cache:/path/to/job/cache"]         # 和全局 cache_dir 对应
    shm_size = 0                 # 不改就是默认 64MB
    dns = []
    dns_search = []
    # allowed_images = ["*/*:*"] # 不配=不限
    # allowed_services = ["*/*:*"]

这个意思是：

默认用 ubuntu:22.04 跑 Job（除非 .gitlab-ci.yml 里指定了别的 image）。
有本地镜像就用本地，没本地才去 pull（if-not-present）。
不开 privileged。

3. `[runners.docker]` 关键字段详解（配合你的场景）

3.1 `image`

[runners.docker]
  image = "ubuntu:22.04"

Runner 的默认 Job 镜像。
如果 .gitlab-ci.yml 没写 image:，就用这个。
写了就以 .gitlab-ci.yml 为准。

注意：

写私有镜像时要带完整 registry：
- registry.example.com/ci/ubuntu18.04_8plus_compile:v1.0

3.2 `pull_policy` & `allowed_pull_policies`

[runners.docker]
  pull_policy = ["if-not-present"]
  # allowed_pull_policies = ["always", "if-not-present", "never"]

常见策略（不同版本关键字大小写略有区别，以文档为准）：

always：每次 job 都强制 docker pull。
if-not-present：本地有就用本地，没有才 pull。
never：永远不 pull，只用本地镜像。

推荐：

自己 build 在本地、暂时没 registry：用 if-not-present。
有正规私有 registry：可以用 always，确保拉到最新镜像。
想限制 .gitlab-ci.yml 随便改 pull policy，就用 allowed_pull_policies 白名单。

3.3 `privileged`

[runners.docker]
  privileged = false

true：容器是 特权模式，可以：
- 跑 Docker-in-Docker（docker build 等）。
- 访问更多内核能力、设备。
但风险很大，基本等于把宿主机开门。

建议：

只给可信项目用的专用 Runner 开。
专门用于构建镜像、需要 DinD 的 Runner，可以：
- privileged = true
- 配合 allowed_privileged_images 限定哪些镜像允许特权。

3.4 `volumes` / `cache_dir` —— cache 和挂载怎么搞

# 全局
cache_dir = "/cache"

[[runners]]
  [runners.docker]
    volumes = ["/cache"]

volumes：
- 直接映射到 job 容器里。
- 一般至少挂缓存目录：/cache。
cache_dir：
- Runner 存 cache 的物理路径。
- 用 Docker executor 时，要确保这个目录在 volumes 里挂进容器。

典型写法：

cache_dir = "/cache"

[runners.docker]
  volumes = ["/cache"]

CI cache 才不会“凭空消失”。

3.5 `services` / `[[runners.docker.services]]`

可以在 Runner 级别加默认服务（数据库之类），一般不推荐乱配，容易影响所有项目。

更常用写法是在 .gitlab-ci.yml 里按需写：

services:
  - name: mysql:8
    alias: db

Runner 级别只用于你非常确定所有 Job 都要依赖的公共服务。

3.6 资源限制：`cpus` / `memory` / `shm_size` 等

部分常用：

[runners.docker]
  cpus = "4"
  memory = "4g"
  shm_size = 268435456   # 256MB

用来限制 Job 容器使用资源，防止一个项目吃光整机。
shm_size：对跑浏览器测试、Chrome、某些编译非常重要，默认 64MB 不够时你会遇到奇怪崩溃。

3.7 网络与 DNS：`network_mode` / `extra_hosts` / `dns`

[runners.docker]
  ports = ["8080:80", "8443:443"]
  dns = ["8.8.8.8"]
  extra_hosts = ["gitlab.example.com:10.0.0.10"]
  # network_mode = "bridge" / "host" / etc
  ## host: 代表网络模式为共享物理机网络，容器里监听 80，物理机上也相当于 80 被占用;
  ## bridge: 默认为此模式，相当于job容器与宿主机在同一个交换机;

内网 GitLab、私有 registry、Nexus、Harbor 时，偶尔要配。
network_mode=host 慎用，一般默认 bridge 足够。

3.8 镜像白名单：`allowed_images` / `allowed_services` / `allowed_privileged_images`

[runners.docker]
  allowed_images = ["registry.example.com/ci/*:*", "ubuntu:*"]
  allowed_services = ["mysql:*", "redis:*"]
  allowed_privileged_images = ["registry.example.com/ci/docker-dind:*"]

防止有人在 .gitlab-ci.yml 里随便拉未知镜像（安全治理）。
在大团队/多租户 Runner 上非常有用。

3.9 `helper_image`

一般不用动，除非你有完全离线环境或自建 registry：

[runners.docker]
  helper_image = "my.registry/gitlab/gitlab-runner-helper:x86_64-v${CI_RUNNER_VERSION}"

版本要和 gitlab-runner 对应，不然 prepare 阶段会炸。

4. `.gitlab-ci.yml` 和 `config.toml` 的优先级关系（实战必须搞清）

核心几条记住就行：

config.toml 里的 [runners.docker].image
- 是默认值。
.gitlab-ci.yml 里的 image:（default 或 job 级）
- 有则覆盖默认。
拉镜像逻辑：
- 看 image 最终值 → 根据 pull_policy / allowed_pull_policies 决定怎么拉。
私有仓库使用顺序：
- DOCKER_AUTH_CONFIG（CI/CD 变量 or config.toml）
- Runner 主机的 ~/.docker/config.json（你手动 docker login）
- GitLab 自带 registry 的凭据（GitLab 会随 job 下发）。

5. 一份结合你场景的“推荐配置”

concurrent = 4
cache_dir = "/cache"

[[runners]]
  name = "driver-runner-1"
  url = "https://gitlab.example.com"
  token = "glrt-xxxx"
  executor = "docker"
  request_concurrency = 2

  [runners.docker]
    image = "registry.example.com/ci/base-ubuntu18.04:v1.5"
    pull_policy = ["if-not-present"]
    privileged = false
    volumes = ["/cache"]
    shm_size = 268435456
    allowed_images = [
      "registry.example.com/ci/*:*",
      "ubuntu:*"
    ]
    allowed_services = [
      "mysql:*",
      "redis:*"
    ]

然后 .gitlab-ci.yml：

image: registry.example.com/ci/base-ubuntu18.04:v1.5

stages: [test]

hello:
  stage: test
  script:
    - echo "hello from $CI_RUNNER_DESCRIPTION"

CICD基础 -- GitLab Runner 的安装以及使用

一、通过官方仓库安装

二、使用说明

1. gitlab-runner register 本质在做啥？

2. 交互式注册：每一步什么意思、去哪拿值

2.1 GitLab instance URL

2.2 Runner authentication token（新）或 registration token（旧，已废弃中）

2.3 Description（描述）

2.4 Tags（tag-list）

2.5 是否可以跑未打 tag 的 Job（run untagged jobs）

2.6 是否锁定到当前项目（locked to current project）

2.7 Executor（执行器类型）

3. 常用参数 & 非交互式写法

3.1 核心参数说明

3.2 如何从 UI 正确拿到这些值

4. 一个能直接用的“标准注册脚本模版”

三、反注册销毁废弃的 Runner

1. 先认清你要删的是哪一个 Runner

2. 标准反注册方式

方式 2.1：按 Runner 名称反注册

方式 2.2：按 URL + Token 精确反注册

方式 2.3：一口气清空所有 Runner

四、GitLab Runner 的 docker 配置字段说明

1. 整体模型：Docker executor 到底干了啥

2. 标准 config.toml 示例（Docker 版）

3. [runners.docker] 关键字段详解（配合你的场景）

3.1 image

3.2 pull_policy & allowed_pull_policies

3.3 privileged

3.4 volumes / cache_dir —— cache 和挂载怎么搞

3.5 services / [[runners.docker.services]]

3.6 资源限制：cpus / memory / shm_size 等

3.7 网络与 DNS：network_mode / extra_hosts / dns

3.8 镜像白名单：allowed_images / allowed_services / allowed_privileged_images

3.9 helper_image

4. .gitlab-ci.yml 和 config.toml 的优先级关系（实战必须搞清）

5. 一份结合你场景的“推荐配置”

1. `gitlab-runner register` 本质在做啥？

2. 标准 `config.toml` 示例（Docker 版）

3. `[runners.docker]` 关键字段详解（配合你的场景）

3.1 `image`

3.2 `pull_policy` & `allowed_pull_policies`

3.3 `privileged`

3.4 `volumes` / `cache_dir` —— cache 和挂载怎么搞

3.5 `services` / `[[runners.docker.services]]`

3.6 资源限制：`cpus` / `memory` / `shm_size` 等

3.7 网络与 DNS：`network_mode` / `extra_hosts` / `dns`

3.8 镜像白名单：`allowed_images` / `allowed_services` / `allowed_privileged_images`

3.9 `helper_image`

4. `.gitlab-ci.yml` 和 `config.toml` 的优先级关系（实战必须搞清）