极狐GitLab Runner 概述

极狐GitLab Runner 是一个 Go 二进制文件，可以在两种模式下运行：

1. 极狐GitLab Runner 本地执行作业（"实例" 执行器）。
2. Runner 管理器将作业委托给使用极狐GitLab Runner Helper 拉取产物的自动扩展环境。

对于在实例执行器模式（1）下开发极狐GitLab Runner，唯一需要的设置是一个工作 Go 环境。对于在管理器和 Helper 模式（2）下开发极狐GitLab Runner，设置还需要一个 Docker 构建环境。此外，在 Kubernetes 中运行管理器或 Helper 需要一个工作集群。

以下说明使用 asdf 设置您的 Go 环境以管理 Go 版本。如果您已经有此设置或知道如何操作，可以跳过步骤 2（"安装依赖项和 Go 运行时"）。

为了在本地提供 Docker 和 Kubernetes，步骤 3 将为您设置 Rancher Desktop。如果您不需要其中一个或两个，可以跳过步骤 3（"安装 Rancher Desktop"）或仅在 Rancher Desktop 中禁用 k3s（Kubernetes）。

推荐环境#

建议在本地笔记本电脑或台式机上安装 Go 和 Rancher Desktop 进行开发。可以使用嵌套虚拟化在云中运行 Rancher Desktop（在 VM 中运行 k3s），但设置起来更棘手。

1. 克隆极狐GitLab Runner#

shell
复制
git clone https://gitlab.com/gitlab-org/gitlab-runner.git

如果您正在为自动扩展模式（管理器和 Helper）开发极狐GitLab Runner，您可能希望查看一个或多个 Taskscaler、Fleeting 和相关插件。要使一个软件包的本地更改对其他软件包可见，请使用 Go 工作区。

shell
复制
1git clone https://gitlab.com/gitlab-org/fleeting/taskscaler.git
2git clone https://gitlab.com/gitlab-org/fleeting/fleeting.git
3git clone https://gitlab.com/gitlab-org/fleeting/fleeting-plugin-aws.git
4git clone https://gitlab.com/gitlab-org/fleeting/fleeting-plugin-googlecompute.git
5go work init
6go work use gitlab-runner
7go work use taskscaler
8go work use fleeting
9go work use fleeting-plugin-aws
10go work use fleeting-plugin-googlecompute

2. 安装依赖项和 Go 运行时#

极狐GitLab Runner 项目使用 asdf 来管理依赖项。设置开发环境的最简单方法是使用 asdf。

shell
复制
cd gitlab-runner
asdf plugin add golang
asdf plugin add vale
asdf plugin add yq
asdf install

shell
复制
1sudo apt-get install -y mercurial git-core wget make build-essential
2wget https://storage.googleapis.com/golang/go1.23.6.linux-amd64.tar.gz
3sudo tar -C /usr/local -xzf go*-*.tar.gz
4export PATH="$(go env GOBIN):$PATH"
5YQ_BINARY="yq_$(go env GOHOSTOS)_$(go env GOHOSTARCH).tar.gz"
6wget https://github.com/mikefarah/yq/releases/download/latest/${YQ_BINARY}.tar.gz
7sudo tar -C /usr/local -xzf ${YQ_BINARY}.tar.gz

shell
复制
1sudo yum install mercurial wget make
2sudo yum groupinstall 'Development Tools'
3wget https://storage.googleapis.com/golang/go1.23.6.linux-amd64.tar.gz
4sudo tar -C /usr/local -xzf go*-*.tar.gz
5export PATH="$(go env GOBIN):$PATH"
6YQ_BINARY="yq_$(go env GOHOSTOS)_$(go env GOHOSTARCH).tar.gz"
7wget https://github.com/mikefarah/yq/releases/download/latest/${YQ_BINARY}.tar.gz
8sudo tar -C /usr/local -xzf ${YQ_BINARY}.tar.gz

shell
复制
1wget https://storage.googleapis.com/golang/go1.23.6.darwin-amd64.tar.gz
2sudo tar -C /usr/local -xzf go*-*.tar.gz
3export PATH="$(go env GOBIN):$PATH"
4YQ_BINARY="yq_$(go env GOHOSTOS)_$(go env GOHOSTARCH).tar.gz"
5wget https://github.com/mikefarah/yq/releases/download/latest/${YQ_BINARY}.tar.gz
6sudo tar -C /usr/local -xzf ${YQ_BINARY}.tar.gz

shell
复制
1wget https://storage.googleapis.com/golang/go1.23.6.darwin-amd64.pkg
2open go*-*.pkg
3export PATH="$(go env GOBIN):$PATH"
4YQ_BINARY="yq_$(go env GOHOSTOS)_$(go env GOHOSTARCH).tar.gz"
5wget https://github.com/mikefarah/yq/releases/download/latest/${YQ_BINARY}.tar.gz
6sudo tar -C /usr/local -xzf ${YQ_BINARY}.tar.gz

shell
复制
pkg install go-1.23.6 gmake git mercurial
export PATH="$(go env GOBIN):$PATH"
YQ_BINARY="yq_$(go env GOHOSTOS)_$(go env GOHOSTARCH).tar.gz"
wget https://github.com/mikefarah/yq/releases/download/latest/${YQ_BINARY}.tar.gz
sudo tar -C /usr/local -xzf ${YQ_BINARY}.tar.gz

3. 安装 Rancher Desktop#

Docker 引擎需要创建一个预构建的镜像，该镜像嵌入到极狐GitLab Runner 中，并在使用 Docker 执行器时加载。一个本地 Kubernetes 集群对于开发 Kubernetes 执行器很有帮助。Rancher Desktop 提供了这两者。

要安装 Rancher Desktop，请按照您的操作系统的安装说明进行操作。

4. 安装极狐GitLab Runner 依赖项#

shell
复制
make deps
asdf reshim

对于 FreeBSD 使用 gmake deps

5. 构建极狐GitLab Runner#

使用 Go 工具链编译极狐GitLab Runner：

shell
复制
make runner-and-helper-bin-host

make runner-and-helper-bin-host 是 make runner-bin-host 的超集，此外还负责构建 Runner Helper Docker 存档依赖项。

6. 运行极狐GitLab Runner#

shell
复制
./out/binaries/gitlab-runner run

您可以使用任何常用的命令行参数（包括 --debug）：

shell
复制
./out/binaries/gitlab-runner --debug run

构建 Docker 镜像#

如果您想构建 Docker 镜像，请运行 make runner-and-helper-docker-host，这将：

1. 构建 gitlab-runner-helper 并从中创建一个 helper Docker 镜像。
2. 为 linux/amd64 编译极狐GitLab Runner。
3. 为 Runner 构建一个 DEB 软件包。官方的极狐GitLab Runner 镜像基于 Alpine 和 Ubuntu，Ubuntu 镜像构建使用 DEB 软件包。
4. 构建 gitlab/gitlab-runner 镜像的 Alpine 和 Ubuntu 版本。

极狐GitLab Runner 中的新自动扩展（Taskscaler）（自 15.6.0 起）#

下一个 Runner 自动扩展架构添加了一种新的自动扩展机制，将适用于所有环境。它将取代所有当前的自动扩展机制（例如 Docker Machine）。这种新机制处于预发布状态并正在积极开发中。极狐GitLab Runner 中使用了两个新库：

1. Taskscaler
2. Fleeting

您无需检出这些库即可在 HEAD 使用极狐GitLab Runner，但在自动扩展领域的一些开发可能会在这里进行。除了 Taskscaler 和 Fleeting，还有许多 Fleeting 插件将极狐GitLab Runner 适配到特定的云提供商（例如 Google Compute 或 AWS EC2）。上述书面说明（"克隆极狐GitLab Runner"）展示了如何检出代码，视频（"Runner Shorts"）展示了如何使用它。这些说明展示了如何使用插件与极狐GitLab Runner。

每个插件都将附带如何构建二进制文件和配置底层实例群组的说明。规范的构建和配置说明将与每个插件一起提供，但在此期间，这里有一些一般说明。

构建插件#

要使用插件运行极狐GitLab Runner，请生成可执行二进制文件并将其放在系统的 PATH 中。

要生成二进制文件，请确保 $GOPATH/bin 在您的 PATH 中，然后使用 go install。

每个插件都包含一个路径 ./cmd/<plugin-name>。例如，从 fleeting-plugin-aws 目录开始：

shell
复制
cd cmd/fleeting-plugin-aws/
go install

如果您使用 asdf 管理 go 版本，在生成二进制文件后运行此命令：

shell
复制
asdf reshim

使用插件#

极狐GitLab Runner 以通常的方式启动，但指定一个 instance 执行器。它还在 plugin_config 和 connector_config 下指定一个实例群组、其位置以及有关如何连接到底层实例的一些详细信息。极狐GitLab Runner 应该找到实例群组并创建初始数量的空闲 VM。当一个作业被配置的实例 runner 接管时，它将消耗一个正在运行的 VM 并通过 fleeting-plugin-aws 插件中的 AWS 服务调用替换它。

toml
复制
1[[runners]]
2  name = "local-taskrunner"
3  url = "https://gitlab.com/"
4  token = "REDACTED"
5  executor = "instance"
6  shell = "bash"
7  [runners.autoscaler]
8    max_use_count = 1
9    max_instances = 20
10    plugin = "fleeting-plugin-aws"                                 # Fleeting 插件名称，如上所述构建 [1]。
11    [runners.autoscaler.plugin_config]
12      credentials_file = "/Users/josephburnett/.aws/credentials".  # 能够扩展自动缩放组（ASG）的凭据 [2]。
13      name = "jburnett-taskrunner-asg"                             # ASG 名称。
14      project = "jburnett-ad8e5d54"                                # ASG 项目。
15      region = "us-east-2"                                         # ASG 地区。
16    [runners.autoscaler.connector_config]
17      username = "ubuntu"                                          # ASG 实例模板登录的用户名。
18    [[runners.autoscaler.policy]]
19      idle_count = 5
20      idle_time = 0
21      scale_factor = 0.0
22      scale_factor_limit = 0

如果您使用 SIGTERM 终止极狐GitLab Runner，您可能会看到一些这些进程仍然存在。相反，请使用 SIGQUIT 终止。

注意，ASG 应该禁用自动扩展。极狐GitLab Runner 通过 Taskscaler 库负责自动扩展。

7. 本地运行测试套件#

极狐GitLab Runner 测试套件由 "核心" 测试和执行器测试组成。执行器测试需要在本地计算机上安装某些二进制文件。某些二进制文件无法在所有操作系统上安装。如果没有安装某个二进制文件，则需要此二进制文件的测试将被跳过。

这些是您可以安装的二进制文件：

1. VirtualBox 和 Vagrant；还需要 Vagrant Parallels 插件
2. kubectl 和 minikube
3. Parallels Pro 或 Business 版本
4. PowerShell

安装二进制文件后运行：

shell
复制
make development_setup

要执行测试运行：

shell
复制
make test

Kubernetes 集成测试#

为了正确运行，某些 Kubernetes 集成测试需要特定配置或运行时参数的 Kubernetes 集群。如果集群配置不正确，这些测试将被跳过。以下是开发人员工作站上常用的 Kubernetes 集群的示例配置：

• minikube

shell
复制
minikube delete
minikube config set container-runtime containerd
minikube config set feature-gates "ProcMountType=true"
minikube start

• k3s

shell
复制
k3s server --tls-san=k3s --kube-apiserver-arg=feature-gates=ProcMountType=true

8. 使用选择的 Helper 镜像版本运行测试#

如果您正在开发 Helper 内的功能，您很可能希望使用包含最新更改的 Docker 镜像版本运行测试。

如果您在不传递 -ldflags 的情况下运行测试，version.go 中的默认版本是 development。这意味着 runner 默认拉取带有 latest 标签的 helper 镜像。

Make 目标#

make 目标自动注入 -ldflags。您可以使用以下命令运行所有测试：

shell
复制
make simple-test

make 目标还为 parallel_test_execute 注入 -ldflags，这最常由 CI/CD 作业使用。

自定义 go test 参数#

如果您希望使用更自定义的 go test 命令，可以使用 print_test_ldflags 作为 make 目标：

shell
复制
go test -ldflags "$(make print_test_ldflags)" -run TestDockerCommandBuildCancel -v ./executors/docker/...

在 GoLand 中#

目前，GoLand 不支持动态 Go 工具参数，因此您需要先运行 make print_ldflags，然后将其粘贴到配置中。

为 runner 和 helper 提供本地 Docker 镜像#

您可以使用以下命令构建 runner 和 helper 作为本地 Docker 镜像：

shell
复制
make runner-local-image              # 仅构建 gitlab-runner:local
make helper-local-image              # 仅构建 gitlab-runner-helper:local
make runner-and-helper-local-image   # 构建两者

构建完成后，您可以在本地使用这些镜像。

shell
复制
docker image ls
REPOSITORY                                TAG        IMAGE ID       CREATED         SIZE
gitlab-runner-helper                      local      1e0064619625   5 minutes ago   92.2MB
gitlab-runner                             local      1261a052d4ad   5 minutes ago   195MB

带有 Kubernetes 的 Helper 镜像#

要在本地 Kubernetes 集群中使用本地镜像，您必须正确设置 Docker 上下文。例如，使用 minikube：

shell
复制
eval $(minikube docker-env)
make runner-and-helper-local-image

本地镜像的自定义#

这些目标注重便利性，而非完整性。并非所有可用的 runner 和 helper 配置都可以通过这些 make 目标创建。这些目标仅支持 Linux 镜像创建。

目标架构默认为主机机器架构。基础 runner 镜像版本默认为 CI/CD 配置中指定的版本。您可以通过设置环境变量来测试变体。有关可能值的指导，请检查在 基础镜像容器镜像仓库 中可用的基础镜像。

示例：

shell
复制
1# 制作一个基于 ubuntu 的 runner 和 helper
2LOCAL_FLAVOR=ubuntu make runner-and-helper-local-image
3
4# 指定版本和风格
5RUNNER_IMAGES_VERSION=0.0.1 LOCAL_FLAVOR=ubuntu make runner-and-helper-local-image
6
7# 使用 pwsh 制作 ubuntu helper 镜像
8# 注意：此风格仅支持用于 helper，而不支持 runner，并且仅在 amd64 上
9LOCAL_FLAVOR=ubuntu-pwsh LOCAL_ARCH=amd64 make helper-local-image

虽然这些环境变量提供了灵活性，但目标不会保护您免受无效配置的影响。对于生产场景，请使用 CI/CD 管道创建的镜像。

9. 安装可选工具#

• 安装 golangci-lint，用于 make lint 目标。
• 安装 markdown-lint 和 vale，用于 make lint-docs 目标。

如果缺少某个工具，在运行 Makefile 目标时会弹出安装说明。

10. 贡献#

您可以开始编写 gitlab-runner 代码。如果您需要一个 IDE 来编辑和调试代码，这里有一些免费的建议可供使用：

• JetBrains GoLand IDE。
• 使用 工作区推荐扩展 的 Visual Studio Code，位于 .vscode/extensions.json。

管理构建依赖项#

极狐GitLab Runner 使用 Go Modules 来管理其依赖项。

不要从上游默认分支添加依赖项，当版本标签可用时。

测试#

Runner 代码库在以下方式中区分单元测试和集成测试：

• 单元测试文件后缀为 _test.go，并在头部包含以下构建指令：

  go
  复制
  // go:build !integration
  

• 集成测试文件后缀为 _integration_test.go，并在头部包含以下构建指令：

  go
  复制
  // go:build integration
  

  可以通过在 go test 命令中添加 -tags=integration 来运行。

要测试测试文件中的构建指令状态，可以使用 make check_test_directives。

在非 Windows 环境上为 Windows 开发#

我们提供了一个 Vagrantfile 来帮助您运行 Windows Server 2019 或 Windows 10 实例，因为我们在 Vagrant 中使用了 多机器。

以下是必需的：

• 安装 Vagrant。
• 安装 Virtualbox。
• 在计算机上大约需要 30GB 的可用硬盘空间。

使用哪个虚拟机取决于您的用例：

• Windows Server 机器已预安装 Docker，应该始终在为 Windows 开发极狐GitLab Runner 时使用。
• Windows 10 机器用于提供一个带有 GUI 的 Windows 环境，这有时可以帮助您调试某些 Windows 功能。请注意，您无法在 Windows 10 上运行 Docker，因为不支持嵌套虚拟化。

运行 vagrant up windows_10 将为您启动 Windows 10 机器。要：

• 进入 Windows 10 机器内部，运行 vagrant ssh windows_10。
• 要访问 Windows 10 的 GUI，您可以通过运行 vagrant rdp windows_10 连接到机器，使用本地安装的 RDP 程序。

对于这两台机器，极狐GitLab Runner 源代码是双向同步的，因此您可以使用自己喜欢的编辑器从计算机上进行编辑。源代码可以在 $GOROOT 环境变量下找到。我们有一个 RUNNER_SRC 环境变量，您可以使用它来找到完整路径，因此在使用 PowerShell 时，您可以使用 cd $Env:RUNNER_SRC。

其他资源#

1. 审查极狐GitLab Runner 合并请求
2. 添加对新 Windows 版本的支持