GitLab Runner 使用指南

1. 概述

GitLab Runner 是 GitLab CI/CD 的核心执行组件，用于运行任务并将结果返回给 GitLab。它是构建 GitLab 持续集成与持续部署流水线不可或缺的一部分。

作为一个运行在独立机器或容器中的代理程序，GitLab Runner 的主要职责是执行 GitLab CI/CD 配置中定义的任务。当我们向 GitLab 仓库提交代码时，Runner 会自动获取任务、执行指定命令，并将执行结果反馈给 GitLab。

通过使用 GitLab Runner，我们可以实现构建、测试和部署流程的自动化，从而节省时间并降低人为错误的风险。

在本文中，我们将介绍 GitLab Runner 的安装、配置及其核心功能，帮助你快速上手并灵活使用。

2. 快速入门

在使用 GitLab Runner 之前，我们需要先完成安装、注册和基础配置。本节将一步步引导你完成这些操作。

2.1. 安装 GitLab Runner

首先，我们需要在目标机器上安装 GitLab Runner。GitLab Runner 支持多种操作系统，包括 Linux、macOS 和 Windows，不同系统下的安装方式略有不同。

以 Debian 系统为例，我们可以通过添加官方仓库并使用 apt 安装：

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

这段命令会下载并运行 GitLab Runner 的安装脚本，随后将 gitlab-runner 包安装到系统中。

更多系统的安装说明可参考 GitLab Runner 官方文档。

2.2. 注册 Runner

安装完成后，下一步是将 Runner 注册到 GitLab 实例中。注册过程会建立 Runner 与 GitLab 的连接，使其能够接收并执行任务。

注册前需要从 GitLab 项目的 Settings > CI/CD > Runners 页面中获取注册 Token。

获取 Token 后，使用以下命令注册 Runner：

$ sudo gitlab-runner register

该命令会引导你输入 GitLab 实例地址、Token、Runner 描述以及执行器类型（如 shell、Docker、Kubernetes）等信息。

注册完成后，Runner 即可开始接收任务。

2.3. 配置 Runner

注册完成后，Runner 的配置信息会保存在 config.toml 文件中（Linux 系统下通常位于 /etc/gitlab-runner/config.toml）。

我们可以在该文件中调整 Runner 的并发限制、缓存设置、环境变量等。

例如，限制并发任务数为 4：

concurrent = 4

定义环境变量供任务使用：

[[runners]]
  environment = ["MY_VARIABLE=value"]

完成配置后，Runner 即可按照需求执行 CI/CD 流水线任务。

3. GitLab CI/CD 配置

Runner 准备就绪后，接下来我们需要在项目根目录创建 .gitlab-ci.yml 文件，用于定义流水线任务。

3.1. 创建 .gitlab-ci.yml 文件

.gitlab-ci.yml 是 GitLab CI/CD 的核心配置文件，用于定义任务、阶段、变量等流水线信息。

在项目根目录下创建 .gitlab-ci.yml 文件，例如：

stages:
  - build
  - test

build-job:
  stage: build
  script:
    - echo "Building the project..."
    - npm install
    - npm run build

test-job:
  stage: test
  script:
    - echo "Running tests..."
    - npm run test

3.2. 定义任务和阶段

任务（Job）表示一个具体的执行步骤，阶段（Stage）定义任务的执行顺序。多个任务可以分配到同一个阶段中，并行执行。

例如，上面的配置文件中定义了两个阶段：

• build
• test

每个阶段包含一个任务，分别执行构建和测试操作。

3.3. 使用变量和密钥

GitLab 支持通过变量和密钥来配置流水线，其中变量用于存储非敏感信息，密钥用于存储敏感数据（如 API Key、Token）。

变量可在 GitLab 的 Settings > CI/CD > Variables 中定义，并在 .gitlab-ci.yml 中通过 $VARIABLE_NAME 的方式引用：

test-job:
  script:
    - echo "Running tests against $API_URL"
    - npm run test --api-url $API_URL

密钥的使用方式与变量一致，但会在日志中被屏蔽，保障信息安全。

4. 使用 GitLab Runner 执行任务

Runner 安装、注册并配置完成后，现在我们来看它是如何执行任务的。

4.1. Runner 执行流程

当代码提交或合并请求触发流水线后，GitLab 会将任务分发给已注册的 Runner，Runner 会持续轮询 GitLab 以获取新任务。

执行流程如下：

1. 克隆仓库：Runner 会克隆当前提交或分支的代码
2. 准备环境：根据配置的执行器（如 shell、Docker）准备执行环境
3. 执行脚本：运行 .gitlab-ci.yml 中定义的 script 脚本
4. 反馈结果：执行完成后将状态（成功、失败、取消）返回 GitLab

4.2. 执行 Shell 命令

Shell 是定义任务最常见的方式。Runner 会在任务环境中执行 Shell 命令，适用于脚本、构建工具、测试套件等场景。

示例任务如下：

test-job:
  script:
    - echo "Running tests..."
    - npm install
    - npm run test

上述任务会依次执行三个命令。若任意命令返回非零退出码，整个任务将标记为失败。

4.3. 使用 Docker 执行任务

Docker 是执行任务时常用的隔离环境。GitLab Runner 原生支持 Docker，可以在任务中指定 Docker 镜像来运行任务。

例如：

test-job:
  image: node:14
  script:
    - npm install
    - npm run test

Runner 会自动拉取 node:14 镜像，并在容器中执行任务，确保环境一致性和可重复性。

5. 总结

本文介绍了 GitLab Runner 的安装、注册、配置以及如何结合 .gitlab-ci.yml 文件实现 CI/CD 流程自动化。

通过 GitLab Runner，我们能够灵活地控制任务执行环境，提升开发效率，保障代码质量。无论是简单的 Shell 脚本执行，还是复杂的 Docker 环境构建，GitLab Runner 都能胜任。

希望本文能帮助你更好地理解和使用 GitLab Runner，为你的 CI/CD 实践提供有力支持。