自动创建并注册 GitLab Runner

本教程介绍如何自动完成 Runner 的创建和注册。流程分为四步：创建个人访问令牌、创建 Runner 配置、自动安装并注册 GitLab Runner，以及查看使用相同配置的 Runner。

这里使用的是 Runner 身份验证令牌，它取代了已弃用的注册令牌方式。更多信息见原文参考链接中的“新的 Runner 注册工作流”。

开始之前

• GitLab 实例上必须已安装 GitLab Runner。
• 创建实例 Runner 需要管理员权限。
• 创建群组 Runner 需要管理员权限或该群组的 Owner 角色。
• 创建项目 Runner 需要管理员权限或该项目的 Maintainer 角色。

创建访问令牌

访问令牌用于通过 REST API 创建 Runner。可以创建用于共享、群组与项目 Runner 的个人访问令牌，或用于群组与项目 Runner 的群组／项目访问令牌。

创建个人访问令牌

版本历史：GitLab 17.6 引入默认关闭的 buffered_token_expiration_limit 功能标志，可把最长有效期上限扩展到 400 天。能否使用扩展上限由此标志控制。

1. 在右上角选择头像。
2. 选择 Edit profile。
3. 在左侧栏选择 Access → Personal access tokens。
4. 选择 Add new token。
5. 填写名称与到期日期。令牌在该日期的 UTC 午夜失效，例如到期日期为 2024-01-01，会在 2024-01-01 00:00:00 UTC 失效。不填日期时，默认设为当前日期后的 365 天；默认最远也为 365 天。GitLab 17.6 及以后可将上限扩展为 400 天。
6. 在 Select scopes 中勾选 create_runner。
7. 选择 Create personal access token。

创建项目或群组访问令牌

版本历史：同样从 GitLab 17.6 起，默认关闭的 buffered_token_expiration_limit 标志可把最长有效期上限扩展到 400 天。

项目访问令牌只授予单个项目的访问权限，群组访问令牌则授予该群组内所有项目的访问权限。

按以下步骤创建：

1. 在顶部栏选择 Search or go to，找到项目或群组。
2. 在左侧栏选择 Settings → Access tokens。
3. 选择 Add new token。
4. 输入名称；有权限查看该项目或群组的用户都能看到令牌名称。
5. 输入到期日期。到期时刻为所选日期的 UTC 午夜，例如 2024-01-01 表示该日 00:00:00 UTC。不填则默认当前日期后 365 天；默认最远为 365 天，GitLab 17.6 以后可扩展为 400 天。GitLab Self-Managed 的实例级最长有效期设置还可能进一步限制此上限。
6. 在 Select a role 下拉框中，项目令牌选择 Maintainer，群组令牌选择 Owner。
7. 在 Select scopes 中勾选 create_runner。
8. 选择 Create project access token。

创建 Runner 配置

Runner 配置用于按需设置 Runner。创建配置后会获得用于注册 Runner 的身份验证令牌。使用相同令牌注册时，一个或多个 Runner 可以关联同一配置。Runner 配置保存在 config.toml 中。

可以使用 GitLab REST API，或者 gitlab_user_runner Terraform 资源创建配置。

使用 GitLab REST API

首先准备 GitLab 实例 URL。例如，项目地址为 gitlab.example.com/yourname/yourproject 时，实例 URL 为 https://gitlab.example.com。创建群组或项目 Runner 时，还需要群组／项目的 ID；该 ID 显示在概览页的名称下方。

将访问令牌传给 POST /user/runners REST 端点，用 curl 创建 Runner：

项目 Runner

curl --silent --request POST --url "https://gitlab.example.com/api/v4/user/runners"
  --data "runner_type=project_type"
  --data "project_id=<project_id>"
  --data "description=<your_runner_description>"
  --data "tag_list=<your_comma_separated_job_tags>"
  --header "PRIVATE-TOKEN: <project_access_token>"

群组 Runner

curl --silent --request POST --url "https://gitlab.example.com/api/v4/user/runners"
  --data "runner_type=group_type"
  --data "group_id=<group_id>"
  --data "description=<your_runner_description>"
  --data "tag_list=<your_comma_separated_job_tags>"
  --header "PRIVATE-TOKEN: <group_access_token>"

共享 Runner

curl --silent --request POST --url "https://gitlab.example.com/api/v4/user/runners"
  --data "runner_type=instance_type"
  --data "description=<your_runner_description>"
  --data "tag_list=<your_comma_separated_job_tags>"
  --header "PRIVATE-TOKEN: <personal_access_token>"

将返回的 token 保存到安全位置或密钥管理系统。这个值只会在 API 响应中返回一次。

使用 gitlab_user_runner Terraform 资源

要通过 Terraform 创建 Runner 配置，可以使用 GitLab Terraform Provider 提供的 gitlab_user_runner 资源。示例配置如下：

resource "gitlab_user_runner" "example_runner" {
  runner_type = "instance_type"
  description = "my-runner"
  tag_list = ["shell", "docker"]
}

自动安装并注册 Runner

如果把 Runner 部署在公有云虚拟机上，可以自动完成安装和注册。创建 Runner 及其配置后，可以复用相同的 Runner 身份验证令牌，注册多个使用相同配置的 Runner。

例如，在目标计算主机上部署具有相同执行器类型和作业标签的多个实例 Runner。每个使用同一身份验证令牌注册的 Runner，都有唯一的 system_id；GitLab Runner 会随机生成它，并保存在本地文件系统。

以下是向 Google Compute Engine 注册和部署 Runner 的自动化工作流示例：

1. 使用 Terraform 基础设施即代码，将 Runner 应用安装到 Google Cloud Platform（GCP）虚拟机。
2. 在 GCP Terraform Provider 中，用 metadata 键把 Runner 身份验证令牌加入 GCP 虚拟机的 Runner 配置文件。
3. 使用由 GCP Terraform Provider 填充的 cloud-init 脚本，向目标 GitLab 实例注册 Runner。示例如下：

#!/bin/bash
apt update
curl --location "https://packages.gitlab.com/install/repositories/runner/
gitlab-runner/script.deb.sh" | bash
GL_NAME=$(curl 169.254.169.254/computeMetadata/v1/instance/name
--header "Metadata-Flavor:Google")
GL_EXECUTOR=$(curl 169.254.169.254/computeMetadata/v1/instance/attributes/
gl_executor --header "Metadata-Flavor:Google")
apt update
apt install -y gitlab-runner
gitlab-runner register --non-interactive --name="$GL_NAME" --url="https://gitlab.com"
  --token="$RUNNER_TOKEN" --request-concurrency="12" --executor="$GL_EXECUTOR"
  --docker-image="alpine:latest"
systemctl restart gitlab-runner

查看使用相同配置的 Runner

完成自动创建和注册后，可以在 GitLab 界面查看使用同一配置的 Runner：

1. 在右上角选择 Admin。
2. 在左侧栏选择 CI/CD → Runners。
3. 在搜索框输入 Runner 描述，或浏览 Runner 列表。
4. 在 Details 标签页的 Runners 旁选择 Show details，查看使用相同配置的 Runner。