极狐GitLab Runner

极狐GitLab Runner 是在流水线中运行作业的应用，与极狐GitLab CI/CD 配合运作。

使用 JihuLab.com SaaS Runner

如果您使用 JihuLab.com，则可以在极狐GitLab 托管的 SaaS Runner 上运行 CI/CD 作业。 这些 Runner 由极狐GitLab 管理并与 JihuLab.com 完全集成。默认情况下，所有项目都启用这些 Runner。 如果您拥有项目的所有者角色，您可以禁用 Runner。

使用私有化部署的 Runner

您也可以安装极狐GitLab Runner 并在 JihuLab.com 或您的实例上注册您自己的 Runner。要使用私有化部署的 Runner，您需要在您拥有或管理的基础设施上安装极狐GitLab Runner。

伸缩 Runner 队列

当您的组织扩展到拥有 Runner 队列时，您应该计划如何监控和调整这些 Runner 的性能。

极狐GitLab Runner 版本

由于兼容性原因，极狐GitLab Runner 的 主版本.小版本 应和极狐GitLab 的 主版本.小版本 保持同步。老版本的极狐GitLab Runner 可能适用于新版本的极狐 GitLab，反之亦然。但是如果存在版本差异，功能特性可能不可用或无法正常工作。

note 极狐GitLab Runner 15.0 向注册 API 请求格式引入了一个变更。它能防止极狐GitLab Runner 与低于 14.8 的极狐GitLab 实例通信。您必须使用与极狐GitLab 版本匹配的 Runner 版本，或者升级极狐GitLab 应用程序。

在小版本更新之间保证向后兼容。但是有时小版本更新会引入要求极狐GitLab Runner 处于相同版本的新特性功能。

Runner 注册

在您安装应用后，您注册了个人的 Runner。Runner 是运行来自极狐GitLab 的 CI/CD 作业的代理。

当您注册 Runner 时，您在极狐GitLab 实例和安装了极狐GitLab Runner 的机器之间建立通信。

Runner 通常在您安装了极狐GitLab Runner 的机器上处理作业。除此之外，您也可以在容器中，在 Kubernetes 集群中，或在云端的弹性伸缩主机上运行 Runner 处理作业。

执行器

当您注册 Runner 时，您必须选择一个执行器。

执行器决定每个作业运行的环境。

例如：

  • 如果您想要 CI/CD 作业运行 Powershell 命令，您可以在 Windows 服务器上安装极狐GitLab Runner，然后注册使用 Shell 执行器的 Runner。
  • 如果您想要 CI/CD 作业在自定义 Docker 容器中运行命令，您可以在 Linux 服务器上安装极狐GitLab Runner，然后注册使用 Docker 执行器的 Runner。

以上只是几种可能的配置。您可以在虚拟机上安装极狐GitLab Runner，并让它使用另一个虚拟机作为执行器。

当您在 Docker 容器中安装极狐GitLab Runner，并选择 Docker 执行器运行作业时，有时被称为 “Docker-in-Docker” 配置。

谁有权限在 UI 中访问 Runner

在您注册 Runner 之前，您应该确定是否每个人应该有权访问。或者您想要限制其适用于指定的群组或项目。

根据您想要允许访问的用户，分为三种类型的 Runner：

Runner 的范围在注册期间定义。Runner 就是这样知道它适用于哪些项目的。

标签

当您注册 Runner 时，您可以向其添加标签。

当运行 CI/CD 作业时，通过分配的标签确定要使用的 Runner。 标签是为作业过滤可用 Runner 列表的唯一方式。

例如，如果一个 Runner 有 ruby 标签，您可以将此代码添加到您项目中的 .gitlab-ci.yml 文件：

job:
  tags:
    - ruby

当运行作业时，使用带有 ruby 标签的 Runner。

配置 Runner

您可以通过编辑 config.toml 文件来配置 Runner。该文件在 Runner 安装过程中同时安装。

在该文件中，您可以为指定 Runner 或全部 Runner 编辑设置。

您可以指定日志记录和缓存等设置。您可以设置并发、内存、CPU 限制等。

监控 Runner

您可以使用 Prometheus 监控您的 Runner。 您可以查看例如正在运行的作业数量，和正在使用的 CPU 资源等指标。

使用 Runner 运行作业

在为您的项目配置 Runner 并使其可用后，您的 CI/CD 作业可以使用 Runner。

特性

极狐GitLab Runner 具有以下特性。

  • 并行运行多个作业。
  • 在多个服务器上使用多个令牌（甚至每个项目）。
  • 限制每个令牌的并发作业数。
  • 作业可以在以下环境运行作业：
    • 本地。
    • 使用 Docker 容器。
    • 使用 Docker 容器并通过 SSH 执行作业。
    • 在不同的云和虚拟化平台上使用弹性伸缩的 Docker 容器。
    • 连接到远程 SSH 服务器。
  • 使用 Go 语言编写并作为单个二进制文件分发，没有任何其它需求。
  • 支持 Bash、PowerShell Core 和 Windows PowerShell。
  • 适用于 GNU/Linux、macOS 和 Windows（可以运行 Docker 的几乎任何环境）。
  • 允许自定义作业运行环境。
  • 无需重启即可自动重新加载配置。
  • 易于使用的设置，支持 Docker、Docker-SSH、Parallels 或 SSH 运行环境。
  • 启用缓存 Docker 容器。
  • 轻松安装为 GNU/Linux、macOS 和 Windows 的服务。
  • 嵌入式 Prometheus 指标 HTTP 服务器。
  • 支持被监控，并将 Prometheus 指标和其他特定作业的数据传递给极狐GitLab。

Runner 执行流程

下图展示 Runner 是如何注册的，以及如何请求和处理作业。同时还展示哪些操作使用注册、认证，以及作业令牌。

sequenceDiagram participant GitLab participant GitLabRunner participant Executor opt registration GitLabRunner ->>+ GitLab: POST /api/v4/runners with registration_token GitLab -->>- GitLabRunner: Registered with runner_token end loop job requesting and handling GitLabRunner ->>+ GitLab: POST /api/v4/jobs/request with runner_token GitLab -->>+ GitLabRunner: job payload with job_token GitLabRunner ->>+ Executor: Job payload Executor ->>+ GitLab: clone sources with job_token Executor ->>+ GitLab: download artifacts with job_token Executor -->>- GitLabRunner: return job output and status GitLabRunner -->>- GitLab: updating job output and status with job_token end

词汇表

本词汇表提供与极狐GitLab Runner 相关的术语定义。

  • 极狐GitLab Runner：您安装的用于在目标计算平台上执行极狐GitLab CI 作业的应用程序。
  • runner configuration：config.toml 文件中的 [[runner]] 入口，它们会被展示在 UI 上的 runner 部分。
  • Runner Manager：一种 Runner，可以创建多个用于弹性伸缩的 Runner。具体到使用的执行器类型。
  • Runner：在被选中的机器上执行作业的进程。取决于执行器的类型，机器可以是本地的（shell 或 docker 执行器），也可以是由自动扩缩容创建的远程机器（docker-autoscaler 或 kubernetes 执行器）。
  • 机器：Runner 运行所需的虚拟机或 pod。极狐GitLab Runner 会自动生成一个独一无二、永久的机器 ID，以便当多个机器被赋予相同的 Runner 配置时，作业可以单独路由，并且 Runner 配置可以在 UI 中被分组。

Troubleshooting

学习常见问题的故障排查手段。