Gitlab有个不错的特性，就是你可以使用自己的Gitlab CI Runner. 可是，如果你没有“自己”的CI Runner该怎么办呢？别担心，我们可以自己写一个。[]~(￣▽￣)~*

在这篇文章里，我们会：

• 阐述Gitlab Runner的核心任务；
• 分析Runner工作时和Gitlab的交互内容；
• 设计和实施一个我们自己的Runner；
• 自举：让我们的Runner运行自己的CI工作；
• 埋一个彩蛋！

当然，如果你习惯直接看代码，欢迎访问Github仓库。如果喜欢，欢迎留个star.

核心任务

打蛇打七寸，Gitlab Runner最核心的任务是这些：

1. 从Gitlab拉取工作；
2. 获取工作后，准备一个独立隔离可重复的环境；
3. 在环境中运行工作，上传运行日志；
4. 在工作完成/异常退出后上报执行结果（成功/失败）。

我们DIY的Runner同样要完成这些任务。

抽丝剥茧

接下来我们按顺序捋一捋各个核心任务，同时观察Runner是怎么和Gitlab交互的。

为了行文简明，下文的API请求和返回的内容有精简。

注册

如果你用过自托管的Gitlab Runner，你应该熟悉这个页面：

用户在这个页面获取注册token，然后通过gitlab-runner register命令把Runner实例注册到Gitlab.

这个注册过程本质上是在调用接口POST /api/v4/runners，其body形如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

{
    "description": "一段用户自己提供的描述",
    "info": {
        "architecture": "amd64", # runner的架构
        "features": { # runner具备的特性，Gitlab可能会拒绝不具备某些特性的runner注册
          "trace_checksum": true, # 是否支持计算上传日志的checksum
          "trace_reset": true,
          "trace_size": true
        },
        "name": "gitlab-runner",
        "platform": "linux",
        "revision": "f98d0f26",
        "version": "15.2.0~beta.60.gf98d0f26"
    },
    "locked": true,
    "maintenance_note": "用户提供的维护备注",
    "paused": false,
    "run_untagged": true,
    "token": "my-registration-token" # Gitlab提供的注册token
}

如果注册token无效，Gitlab会返回403 Forbidden。在成功注册时会返回：

1
2
3
4
5

{
    "id": 2, # Runner在Gitlab这边的全局编号
    "token": "bKzi84WitiHSN4N4TYU6", # runner的鉴权token
    "token_expires_at": null # 据我观察，这个字段对应的功能没有做
}

Runner只关心其中的token，它代表了runner的身份，同时作为共享密钥参与后面的API调用的鉴权。这个token会连同其他设置被保存到文件~/.gitlab-runner/config.toml中。

拉取工作

Runner在设定中有个最大并行工作数，在目前执行的工作数目小于设定值时，它会轮询POST /api/v4/jobs/request以获取工作，传入的body很像注册时的body，形如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

{
    "info": {
        "architecture": "amd64", # runner的架构
        "executor": "docker", # runner使用的执行器
        "features": { # runner具备的特性，例如，如果一个runner不支持上传产物，那么需要上传产物的工作就不会调度到它身上。
            "artifacts": true,
            "artifacts_exclude": true,
            "cache": true,
            "cancelable": true,
            "image": true
        },
        "name": "gitlab-runner",
        "platform": "linux",
        "revision": "f98d0f26",
        "shell": "bash",
        "version": "15.2.0~beta.60.gf98d0f26"
    },
    "last_update": "d8a43f53bb125ec6599d778b9969a601", # 游标
    "token": "bKzi84WitiHSN4N4TYU6" # 前面注册时拿到的token
}

如果没有要执行的工作，Gitlab会返回状态码204 No Content，Header中会有游标，形如X-Gitlab-Last-Update: 2794e577289a38db0df0e93e3215f597，供下次请求传入。

游标其实是个随机字符串，请求进入Gitlab的前置代理（名为Workhorse）时，代理会检查Runner提交的游标是否和Redis中的游标一致，如果一致就让Runner等着（long poll），不一致就把请求原样代理到Gitlab后端。Redis中的游标的更新由后端维护，在变更时会通过Redis Pub/Sub通知到Workhorse. 工作的选取在后端实现为一个复杂的SQL查询。

在有新工作需要执行时，Gitlab会返回201 Created，其body形如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

{
    "allow_git_fetch": true,
    "artifacts": null, # 要上传的产物
    "cache": [], # 要使用的缓存
    "credentials": [
        {
            "password": "jTruJD4xwEtAZo1hwtAp", # 用来拉取代码、上传日志、上报执行结果的通用密钥
            "type": "registry",
            "url": "gitlab.example.com",
            "username": "gitlab-ci-token" # 用户名是固定的
        }
    ],
    "dependencies": [],
    "features": {
        "failure_reasons": [ # 服务端可接受的工作错误原因
            "unknown_failure",
            "script_failure"
        ]
    },
    "git_info": {
        "before_sha": "6b55b6ffd17b57a2ec0cf8e7d7c66ff709343528",
        "depth": 20, # 克隆深度
        "ref": "master", # 目标分支/tag
        "ref_type": "branch",
        "refspecs": [
            "+refs/pipelines/52:refs/pipelines/52",
            "+refs/heads/master:refs/remotes/origin/master"
        ],
        "repo_url": "http://gitlab-ci-token:[email protected]/flightjs/Flight.git",
        "sha": "cb4717728e8f885558a4e0bb28c58288b8bf4746" # commit hash
    },
    "id": 823, # 工作id，是后面很多API调用的重要参数
    "image": null,
    "job_info": {
        "id": 823,
        "name": "build-job",
        "project_id": 6,
        "project_name": "Flight",
        "stage": "build"
    },
    "services": [],
    "steps": [ # 要执行的脚本
        {
            "allow_failure": false,
            "name": "script",
            "script": [ # 脚本内容，每项对应 .gitlab-ci.yml 中的一个数组元素
                "echo \"sleeping 1\"",
                "sleep 5",
                "echo \"sleeping 2\"",
                "sleep 5"
            ],
            "timeout": 3600, # 脚本最大执行超时
            "when": "on_success"
        }
    ],
    "token": "jTruJD4xwEtAZo1hwtAp", # job凭据，用来鉴权后面的API调用
    "variables": [ # job执行时的环境变量，用户自己定义的环境变量也会放在这里
        {
            "key": "CI_JOB_ID",
            "masked": false,
            "public": true,
            "value": "823"
        },
        {
            "key": "CI_JOB_URL",
            "masked": false,
            "public": true,
            "value": "http://gitlab.example.com/flightjs/Flight/-/jobs/823"
        },
        {
            "key": "CI_JOB_TOKEN",
            "masked": true,
            "public": false,
            "value": "jTruJD4xwEtAZo1hwtAp"
        }
    ]
}

准备环境和克隆仓库

为了让CI的执行稳定、可重复，Runner执行的环境需要一定程度的隔离，执行环境的准备、脚本的执行由Executor负责，聊几个常见的：

• Shell：
  • 好处：调试容易，易于理解；
  • 坏处：隔离级别很低，只提供基于文件目录的隔离，项目依赖、可用端口会在CI job之间相互影响。
• Docker或k8s：
  • 好处：除了操作系统内核，其他资源都隔离了；镜像生态丰富，CI job可重复性高。
  • 坏处：不适用于不可信的工作负载。
• VirtualBox或Docker Machine：
  • 好处：操作系统级别的隔离，安全性高。
  • 坏处：挺重的，拖累CI执行效率。

所有的Executor都提供必须的API供Gitlab Runner调用：

• 准备环境；
• 执行Runner提供的脚本，获取执行时的输出，返回执行结果（这个API会被调用多次）；
• 清理环境。

克隆仓库其实就是在环境中执行一个git clone，所需参数在上一步“拉取工作”中获得:

1

git clone -b [分支/tag名] --single-branch --depth [克隆深度] https://gitlab-ci-token:[email protected]/user/repo.git [克隆目的地文件夹名称]

执行工作和上传日志

所有要执行的工作都会被Runner编排成几个脚本文本，发给Executor执行，编排时会考虑Executor里的脚本执行环境是哪一个（bash/Powershell）。环境变量会放在编排的脚本最前面，例如对于bash环境，环境变量在脚本中使用export声明。

说个有趣的，你在CI log里看到的，标识为绿色的接下来要执行的语句是Runner在编排脚本时用echo命令+终端颜色控制符输出的，类似这样：

1
2

echo -e $'\x1b[32;1m$ date\x1b[0;m' # 打印出绿色的 $ date
date # 真正执行 date 命令

执行器的标准输出和标准错误会被Runner捕获，存放在/tmp临时文件中。job执行结束前，Runner会周期性地调用接口PATCH /api/v4/jobs/{job_id}/trace增量上传日志，请求的header形如：

Host: gitlab.example.com
User-Agent: gitlab-runner 15.2.0~beta.60.gf98d0f26 (main; go1.18.3; linux/amd64)
Content-Length: 314 # 这个增量的长度
Content-Range: 0-313 # 这个增量在全部日志中的位置
Content-Type: text/plain
Job-Token: jTruJD4xwEtAZo1hwtAp
Accept-Encoding: gzip

body里就是这批增量上传的日志，本例形如：

\x1b[0KRunning with gitlab-runner 15.2.0~beta.60.gf98d0f26 (f98d0f26)\x1b[0;m
\x1b[0K  on rockgiant-1 bKzi84Wi\x1b[0;m
section_start:1663398416:prepare_executor
\x1b[0K\x1b[0K\x1b[36;1mPreparing the "docker" executor\x1b[0;m\x1b[0;m
\x1b[0KUsing Docker executor with image ubuntu:bionic ...\x1b[0;m
\x1b[0KPulling docker image ubuntu:bionic ...\x1b[0;m

下一次上传日志时，新请求的Content-Range和Content-Length的内容同样会对应请求body的信息。

Gitlab在成功接受请求后会返回202 Accepted，返回的header中有一些有意思的值：

Job-Status: running # job运行状态
Range: 0-1899 # 当前收到的字节范围，每次都是0-n这个形式
X-Gitlab-Trace-Update-Interval: 60 # runner最低上报间隔，单位秒

这里有一个有意思的优化，当CI log页面有用户正在观看时，X-Gitlab-Trace-Update-Interval的值会是3，即Runner应该3秒就增量上报一次日志，这样用户才能更实时地看到最新进展。

上报执行结果

在用户定义的脚本执行成功或失败后，Runner会做两件事：

• 如果还有没上传的日志，按前述方法将剩余日志全部上传；
• 调用PUT /api/v4/jobs/{job_id}更新job的状态。

一个成功的job对应的HTTP body形如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
    "checksum": "crc32:4a182676", # 所有日志的CRC32校验，用来让服务端确定所有日志都已经成功上传
    "info": { ... }, # 这个字段已经在前面见过很多次了，内容从略
    "output": {
        "bytesize": 1899, # 日志的总字节数
        "checksum": "crc32:4a182676" # 同checksum
    },
    "state": "success", # job执行结果
    "token": "jTruJD4xwEtAZo1hwtAp" # job凭据
}

一个失败的job对应的HTTP body形如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
    "checksum": "crc32:f67200bc",
    "exit_code": 42, # 用户脚本的退出码
    "failure_reason": "script_failure", # 错误原因，从一个与服务端约定的列表里选
    "info": { ... }, # 这个字段已经在前面见过很多次了，内容从略
    "output": {
        "bytesize": 1723,
        "checksum": "crc32:f67200bc"
    },
    "state": "failed", # job执行结果
    "token": "Lx1oBNfw2e9xhZvNKsdX"
}

Gitlab后端在成功接受状态更新请求后会返回200 OK，Runner的工作就结束了。

有时，服务端没准备好接受状态更新（日志的处理是异步的，还没落盘），此时会返回202 Accepted，header里的X-GitLab-Trace-Update-Interval会告知Runner在下次尝试之前的等待时间（类似指数退避），Runner会一直重发请求，直到服务端返回200 OK或者超过最大重试次数。

时序图

整体来看，上述流程是这样子的：

sequenceDiagram
    autonumber
    Runner->>Gitlab: 拉取job（long pull）
    Gitlab-->>Runner: job信息、凭据
    Runner->>Runner: 准备环境和克隆仓库

    loop 执行工作和上传日志
        Runner->>Runner: 执行工作
        Runner->>Gitlab: 增量上传日志
    end

    Runner->>Gitlab: 上报执行结果
    Runner->>Runner: 清理环境，工作结束

开始动手

OK，我们已经把Gitlab Runner的核心任务捋了一遍了，现在该打开IDE，写我们自己的Runner啦！

取个名字

我喜欢吃蛋挞，我们就叫我们的DIY Runner “蛋挞” 吧，英文名Tart.

画个Logo，这样看上去比较像一个正经项目：

再打开编程祖师娘Ada Lovelace的画像拜一拜接受祝福，万事俱备，开工大吉！

规划功能

和Gitlab Runner一样，蛋挞也是个命令行程序，主要功能有：

• 注册（register）：吃Gitlab的注册token，输出配置文件到标准输出，这样我们可以再把它重定向到文件里，还能避（丢）免（给）处（用）理（户）“什么时候该覆盖配置文件”这样的玄学问题。
• 尝试获取和运行一个工作（single）：监听工作，运行工作，提交结果，退出。这个命令主要是为了调试方便。
• 运行多个工作（run）：监听工作，运行工作，提交结果，重复。

用上spf13/cobra，我们可以很快把命令行本体捏出来：

$ tart 
An educational purpose, unofficial Gitlab Runner.

Usage:
  tart [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  register    Register self to Gitlab and print TOML config into stdout
  run         Listen and run CI jobs
  single      Listen, wait and run a single CI job, then exit
  version     Print version and exit

Flags:
      --config string   Path to the config file (default "tart.toml")
  -h, --help            help for tart

Use "tart [command] --help" for more information about a command.

构建隔离的执行环境

构建隔离执行环境可能是Runner的一个最重要的任务了，理想的执行环境应该有这些特征：

• 资源隔离，文件系统、端口、进程空间独享，包括：
  • 不被上一个job影响；
  • 不被同时运行的其他job影响；
  • 不被宿主机的其他进程影响。
• 可重复性：同一个commit对应的job每次执行结果应该是一致的；
• 宿主安全：job的执行不会影响到宿主机或其他job.
• 缓存友好：用空间换时间。

分析现有的Gitlab Runner的Executor各自满足了上述哪些特征就作为留给读者的练习了。

既然蛋挞是我们自己的Runner，我们有充分的自由，让我们选择Firecracker来构建执行环境吧。

Firecracker是亚马逊云服务（AWS）开发和开源的虚拟机管理器，特点是轻量，它依靠KVM实现，通过模拟尽可能少的硬件以及跳过BIOS启动，可以在不到一秒内启动一台具有终端输入输出的虚拟机，并且每台虚拟机的额外内存开销不大于5MB. AWS使用Firecracker来构建自己的函数计算服务Lambda和无服务器托管服务Fargate.

启动一台能供CI使用的MicroVM（Firecracker对虚拟机的称呼）需要三个依赖：

• Linux内核镜像；
• 联通外部网络的TAP设备（一个虚拟的layer-2网络设备）；
• 根文件系统（rootFS，以文件的形式存在，可以类比docker image来理解，里面有操作系统的根/及其下属内容）。

你可以查看蛋挞对它们的具体实现，其中，根文件系统值得说道一下。

还记得我们梳理的Gitlab Runner Executor的必备API吗？虽然蛋挞并不直接仿写Gitlab Runner的Executor，但是这三个操作仍然是必要的：

• 准备环境：按样本复制一份根文件系统交给Firecracker，启动虚拟机。
• 执行Runner提供的脚本，获取执行时的输出，返回执行结果（这个API会被调用多次）：我们稍后讨论。
• 清理环境：关闭虚拟机，删掉根文件系统。

让每个虚拟机都在根文件系统的副本上操作可以提供资源隔离和可重复性。

Firecracker提供的终端只有一个输入和输出，操作自由度不够，这意味着我们在虚拟机里需要一个agent，脚本交给它去执行，输出和退出码由它转交给蛋挞。思来想去，我们最常用的agent恐怕是ssh了：

• 在根文件系统里安装好sshd和登录公钥；
• 每次虚拟机启动后，蛋挞使用ssh去连接虚拟机；
• 蛋挞经过ssh执行命令，获取执行时的输出和执行结果。

sshd会调用虚拟机本地的bash运行蛋挞提供的脚本，这正是我们想要的。

脚本的生成和执行

这步不难，Gitlab提供的用户脚本是一个字符串数组，环境变量是一个对象数组：

• 脚本开头写一个set -euo pipefail，这样执行会在遇到错误的时候停下来；
• git clone和cd到仓库目录；
• export环境变量，每个一行，其中环境变量的值需要escape；
• 写一个set +x，这样bash就会把接下来要执行的每个命令写到标准输出了；
• 写入用户脚本，每个一行；
• 每行末尾记得写断行符\n.

脚本交给sshd后就可以执行了，标准输出和标准错误会被蛋挞实时收集写到本地临时文件中，另有一个进程会把它周期性地增量上传到Gitlab.

脚本执行结束后，sshd会返回退出码，蛋挞会视情况上报job成功或失败。

自举：自己运行自己的CI

既然蛋挞是用来运行CI任务的，我们就找点任务来让它运行，比如……它自己的CI？

让我们为蛋挞写一个.gitlab-ci.yml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

variables:
  # speed up go dependency downloading
  GOPROXY: "https://goproxy.cn,direct"

# we have go and build-essential pre-installed
our-exceiting-job:
  script:
    - echo "run test"
    - go test ./...
    - echo "build tart"
    - make
    - echo "run tart"
    - cd bin
    - ./tart
    - ./tart version

把蛋挞注册为仓库的CI Runner后，禁用shared runner（确保任务调度到蛋挞上），触发一次CI执行，看上去效果还不错！

埋一个彩蛋

每周四，一股神秘力量会笼罩着每个人的群聊和朋友圈。

在周四使用蛋挞运行CI job，体验这股来自东方的神秘力量。

一点历史

2014年~2015年，Gitlab Runner有很多活跃的第三方实现，其中Kamil Trzciński基于Go的GitLab CI Multi-purpose Runner实现被Gitlab相中，替代了Gitlab自己基于Ruby的实现，成为了我们今天看到的Gitlab Runner. 那时Kamil Trzciński还在Polidea工作，因此GitLab CI Multi-purpose Runner是一个社区贡献。开源真是奇妙。

发表说明

本文于2022年12月28日发表于极狐Gitlab公众号。

参考资料

• Gitlab Runner
• Gitlab Rails
• mitmproxy