gitlab Runner 使用教程 – wiki基地

作者： /

GitLab Runner 使用教程：从安装到 CI/CD 自动化

在现代软件开发中，持续集成 (CI) 和持续交付 (CD) 是提高开发效率和软件质量的关键实践。GitLab CI/CD 是 GitLab 提供的一个强大工具，它允许您在每次代码提交时自动运行测试、构建和部署流程。而 GitLab Runner 则是执行这些 CI/CD 任务的代理。

本文将详细介绍 GitLab Runner 的安装、注册、配置以及如何在您的项目中有效地使用它，从而实现 CI/CD 自动化。

1. 什么是 GitLab Runner？

GitLab Runner 是一个开源代理应用程序，它与 GitLab CI/CD 协同工作，用于运行定义在 .gitlab-ci.yml 文件中的作业（jobs）。当您的 GitLab 实例中的 CI/CD 流水线被触发时，GitLab 会将作业发送给一个可用的 Runner，由 Runner 在其运行环境中执行这些作业，并将结果（日志、状态）返回给 GitLab。

Runner 可以安装在各种操作系统上（Linux, Windows, macOS）和不同的环境中（虚拟机、容器、Kubernetes 集群）。

2. 前提条件

在开始安装和配置 GitLab Runner 之前，请确保满足以下条件：

  • GitLab 实例地址：您需要知道您的 GitLab 实例的 URL (例如 https://gitlab.com 或您自托管的 GitLab 地址)。
  • 注册令牌（Registration Token）：在 GitLab 项目、组或管理员区域，您会找到一个用于注册 Runner 的令牌。
    • 项目级别：项目 -> 设置 -> CI/CD -> Runners -> New project runner (或 Specific runners 部分)。
    • 组级别：组 -> 设置 -> CI/CD -> Runners -> New group runner。
    • 实例级别（管理员）：管理区域 -> 概览 -> Runners。
  • 合适的运行环境：一个稳定的服务器或虚拟机，具备足够的资源（CPU, 内存, 磁盘空间）来执行您的 CI/CD 作业。

3. GitLab Runner 的安装

GitLab Runner 提供了多种安装方式，这里我们主要介绍 Linux 和 Docker 的安装方法，因为它们最为常用。

3.1 Linux 安装 (Debian/Ubuntu)

  1. 添加 GitLab 仓库：
    bash
    curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash

  2. 安装 GitLab Runner：
    bash
    sudo apt-get update
    sudo apt-get install gitlab-runner

    • 对于 CentOS/RHEL：
      bash
      curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.rpm.sh" | sudo bash
      sudo yum install gitlab-runner
    • 其他操作系统请参考官方文档。

  3. 启动/停止/重启服务：
    bash
    sudo systemctl start gitlab-runner
    sudo systemctl stop gitlab-runner
    sudo systemctl restart gitlab-runner
    sudo systemctl status gitlab-runner

3.2 Docker 安装

使用 Docker 容器运行 GitLab Runner 是一个非常灵活和推荐的方式，特别是当您希望 Runner 环境与宿主机隔离，或者需要快速部署多个 Runner 时。

  1. 拉取 Runner 镜像：
    bash
    docker pull gitlab/gitlab-runner:latest

  2. 创建配置目录和挂载点：
    Runner 需要一个持久化的配置目录来存储 config.toml 文件。
    bash
    docker volume create gitlab-runner-config
    或者创建一个本地目录：
    bash
    mkdir -p /srv/gitlab-runner/config

  3. 运行 Runner 容器：
    使用 Docker volume 挂载配置：
    bash
    docker run -d --name gitlab-runner --restart always \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v gitlab-runner-config:/etc/gitlab-runner \
    gitlab/gitlab-runner:latest

    • -d: 后台运行。
    • --name gitlab-runner: 容器名称。
    • --restart always: 容器崩溃或重启时自动重启。
    • -v /var/run/docker.sock:/var/run/docker.sock: 允许 Runner 在其内部使用 Docker 命令（当使用 Docker executor 时，Runner 会在宿主机上启动新的 Docker 容器来执行作业）。
    • -v gitlab-runner-config:/etc/gitlab-runner: 挂载 Docker volume 到容器的 /etc/gitlab-runner 目录，用于持久化配置。

    如果使用本地目录挂载：
    bash
    docker run -d --name gitlab-runner --restart always \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v /srv/gitlab-runner/config:/etc/gitlab-runner \
    gitlab/gitlab-runner:latest

4. GitLab Runner 的注册

安装 Runner 后，您需要将其注册到您的 GitLab 实例，以便 GitLab 知道这个 Runner 可以用来执行作业。

  1. 运行注册命令：

    • 对于 Linux 安装：
      bash
      sudo gitlab-runner register

    • 对于 Docker 安装：
      bash
      docker run --rm -it -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner:latest register
      # 或者如果你使用 docker volume:
      # docker run --rm -it -v gitlab-runner-config:/etc/gitlab-runner gitlab/gitlab-runner:latest register
      --rm 会在命令执行完毕后自动删除临时容器。

  2. 根据提示输入信息：

    • Please enter the GitLab instance URL：输入您的 GitLab 实例 URL (例如 https://gitlab.com)。
    • Please enter the registration token：输入您从 GitLab 获取的注册令牌。
    • Please enter a description for the runner：为您的 Runner 输入一个有意义的描述（例如 “My shared Docker runner”）。这有助于您在 GitLab UI 中识别它。
    • Please enter tags for the runner (comma-separated)：输入与此 Runner 关联的标签（例如 docker, linux, frontend）。这些标签非常重要，GitLab 会根据作业中定义的标签来匹配可用的 Runner。留空表示无标签。
    • Please enter an executor：选择一个执行器。常用的有：
      • shell：在 Runner 运行的宿主机上直接执行命令。简单但安全性较低，因为它直接访问宿主机环境。
      • docker：在 Docker 容器中执行每个作业。推荐使用，提供更好的隔离性和一致性。
      • kubernetes：在 Kubernetes 集群中动态创建 Pod 来执行作业。适用于大规模和高度弹性的 CI/CD。
      • 其他：virtualbox, ssh, custom 等。

    如果您选择了 docker 执行器，还会要求输入：
    * Please enter the default Docker image (e.g. ruby:2.7)：为 Docker 执行器指定一个默认的 Docker 镜像。如果 .gitlab-ci.yml 没有指定 image，Runner 将使用此镜像。常用的有 alpine/git, ubuntu:latest, node:latest 等。

  3. 验证注册：
    注册成功后，您会在 Runner 配置文件 (/etc/gitlab-runner/config.toml 或 Docker volume 中) 中看到新增的 Runner 配置。同时，刷新 GitLab UI 的 Runner 页面，您应该能看到新注册的 Runner 处于 绿色 可用状态。

5. Runner 配置 (config.toml)

config.toml 文件是 GitLab Runner 的核心配置文件。它定义了所有注册 Runner 的详细信息和行为。

文件路径：
* Linux 安装：/etc/gitlab-runner/config.toml
* Docker 安装：挂载到容器 /etc/gitlab-runner/config.toml 的宿主机目录或 Docker volume 中。

以下是一个典型的 config.toml 文件结构示例：

“`toml

全局配置

concurrent = 1 # Runner 同时运行的作业数
check_interval = 0 # Runner 检查新作业的时间间隔（秒），0表示立即检查

[[runners]]
name = “My Docker Runner” # Runner 名称
url = “https://gitlab.com/” # GitLab 实例 URL
token = “YOUR_RUNNER_TOKEN” # 注册时生成的 Runner token
executor = “docker” # 执行器类型
[runners.docker]
tls_verify = false # 是否验证 TLS 证书
image = “alpine/git” # Docker 执行器的默认镜像
privileged = false # 是否以特权模式运行容器
disable_entrypoint_overwrite = false # 是否禁用 Docker 镜像的 entrypoint 覆盖
oom_kill_disable = false # 是否禁用 OOM 杀手
disable_cache = false # 是否禁用 Docker 缓存
volumes = [“/cache”] # 挂载到容器的卷，用于缓存
shm_size = 0 # Docker 容器的 /dev/shm 大小
[runners.cache]
type = “s3” # 缓存类型 (s3, gcs, azure, http, file)
path = “cache”
shared = true # 是否在所有 Runner 之间共享缓存
[runners.cache.s3]
BucketName = “my-ci-cache”
ServerAddress = “s3.amazonaws.com”
AccessKey = “YOUR_AWS_ACCESS_KEY”
SecretKey = “YOUR_AWS_SECRET_KEY”

更多 [[runners]] 配置块可以添加多个 Runner

“`

关键配置项说明：

  • concurrent：全局设置，定义 Runner 进程可以同时执行的最大作业数量。
  • check_interval：全局设置，定义 Runner 轮询 GitLab 实例获取新作业的时间间隔（秒）。
  • [[runners]]：每个 [[runners]] 块代表一个注册的 Runner。
    • name: Runner 在 GitLab UI 中显示的名称。
    • url: GitLab 实例的 URL。
    • token: 注册时生成的 Runner 的验证令牌。请注意，这不是注册令牌，而是 Runner 注册后 GitLab 分配给它的独立令牌。
    • executor: 指定执行器类型，如 shell, docker, kubernetes 等。
    • tags: 关联到此 Runner 的标签列表。
    • limit: (可选) 此 Runner 同时可以执行的作业数，覆盖 concurrent 的全局设置。
    • [runners.docker]：仅当 executor = "docker" 时有效。
      • image: 默认的 Docker 镜像。
      • volumes: 可以在 Runner 和作业容器之间共享的卷。常用于挂载 Docker socket 或缓存。
      • privileged: 设为 true 允许容器以特权模式运行，可以访问宿主机的设备（慎用）。
    • [runners.cache]：配置 CI/CD 缓存，用于加速重复任务。可以配置为本地文件系统、S3、GCS 等。

修改 config.toml 后，务必重启 GitLab Runner 服务使配置生效：sudo systemctl restart gitlab-runner (Linux) 或重启 Docker 容器。

6. 在 .gitlab-ci.yml 中使用 Runner

.gitlab-ci.yml 文件是 GitLab CI/CD 的核心，它定义了您的 CI/CD 流水线。在这里，您可以通过 tags 关键字指定哪些类型的 Runner 可以执行某个作业。

示例 .gitlab-ci.yml 文件：

“`yaml
stages:
– build
– test
– deploy

build_job:
stage: build
image: node:16 # 此作业使用 node:16 Docker 镜像
script:
– echo “Building the application…”
– npm install
– npm run build
artifacts: # 缓存构建产物
paths:
– build/
tags:
– docker # 只有带有 ‘docker’ 标签的 Runner 才能执行此作业

test_job:
stage: test
image: python:3.9 # 此作业使用 python:3.9 Docker 镜像
script:
– echo “Running tests…”
– pip install -r requirements.txt
– pytest
tags:
– docker
– python # 此作业需要带有 ‘docker’ 和 ‘python’ 标签的 Runner

deploy_staging:
stage: deploy
script:
– echo “Deploying to staging environment…”
– # 实际部署命令，例如 SSH 到服务器，rsync 文件等
environment:
name: staging
url: https://staging.example.com
only:
– main # 只在 main 分支上执行
tags:
– shell # 此作业可以使用 shell 执行器，可能需要在特定服务器上运行
“`

tags 关键字：
在每个作业中，您可以使用 tags 关键字来指定执行该作业所需的 Runner 标签。GitLab 会查找所有可用且匹配所有指定标签的 Runner。如果未指定 tags，则任何注册的 Runner 都可以执行该作业，前提是它不是 tagged 模式。

7. Runner 类型 (Executors)

GitLab Runner 支持多种执行器，每种执行器都有其优缺点和适用场景：

  • Shell Executor (最简单)：

    • 优点：配置简单，直接在 Runner 所在机器上执行脚本。
    • 缺点：隔离性差，作业之间可能相互影响，安全性较低（特别是当执行不受信任的代码时）。
    • 适用场景：快速启动，或当您需要直接访问宿主机资源（如特定的硬件、已安装的工具）时。

  • Docker Executor (推荐)：

    • 优点：高度隔离，每个作业都在一个独立的 Docker 容器中运行。环境可控，可以指定任何 Docker 镜像。
    • 缺点：需要 Docker 守护进程，引入 Docker 的学习曲线。
    • 适用场景：绝大多数 CI/CD 场景，提供一致、隔离的构建环境。

  • Kubernetes Executor (高扩展性)：

    • 优点：每个作业都在 Kubernetes 集群中动态创建的 Pod 中运行，具备极高的扩展性和弹性。
    • 缺点：配置复杂，需要 Kubernetes 集群知识。
    • 适用场景：大型组织、需要根据负载动态伸缩 Runner 数量、以及利用 Kubernetes 强大调度能力的场景。

  • VirtualBox/Parallels/SSH Executor (特定场景)：

    • 提供在虚拟机或远程 SSH 服务器上执行作业的能力。
    • 适用场景：需要特定操作系统环境（如 macOS 进行 iOS 构建）、或需要在远程服务器上执行特定操作。

8. 最佳实践

  • 使用标签 (Tags)：为您的 Runner 分配有意义的标签，并在 .gitlab-ci.yml 中使用这些标签来精确控制哪些 Runner 执行哪些作业。这有助于分离不同类型作业（例如，前端构建、后端测试、部署）的需求。
  • Runner 隔离：尽可能使用 Docker 或 Kubernetes 执行器来确保作业之间的隔离性，防止环境污染和安全问题。
  • 缓存 (Cache)：合理配置 CI/CD 缓存（例如 Node.js 的 node_modules，Python 的 pip 缓存）可以显著减少构建时间。
  • 工件 (Artifacts)：使用 artifacts 来保存和传递作业的输出（例如编译后的二进制文件、测试报告），以便后续作业或手动下载使用。
  • 按需伸缩：对于大规模 CI/CD，考虑使用 Kubernetes Executor 或 Runner 自动伸缩功能，根据负载动态创建和销毁 Runner 实例。
  • 监控 Runner：定期检查 Runner 的状态和日志，确保它们健康运行。
  • 权限管理： Runner 运行的进程或容器的权限应该最小化，以减少潜在的安全风险。

9. 常见问题与故障排除

  • Runner 离线 (Offline)：
    • 检查 Runner 服务是否正在运行：sudo systemctl status gitlab-runner (Linux) 或 docker ps -a (Docker)。
    • 检查 config.toml 中的 url 和 token 是否正确。
    • 检查网络连接，确保 Runner 可以访问 GitLab 实例。
    • 查看 Runner 日志：sudo journalctl -u gitlab-runner (Linux) 或 docker logs gitlab-runner (Docker)。
  • 作业卡住/Pending：
    • 检查是否有可用的 Runner 匹配作业的所有 tags。
    • 检查 Runner 的 concurrent 或 limit 设置，是否已达到最大并发数。
    • 检查 Runner 的连接状态，是否在线。
  • ERROR: Job failed (system failure): Cannot connect to the Docker daemon：
    • 这通常发生在 Docker Executor 中，意味着 Runner 容器无法连接到 Docker 守护进程。确保 docker.sock 已正确挂载：-v /var/run/docker.sock:/var/run/docker.sock。
    • 检查 Docker 守护进程是否正在运行。
  • 权限问题：
    • 如果 Runner 无法访问某些文件或目录，检查其运行用户（通常是 gitlab-runner 用户）是否有足够的权限。
    • 在 Docker Executor 中，确保挂载的卷具有正确的权限。

10. 总结

GitLab Runner 是实现 GitLab CI/CD 自动化的核心组件。通过正确地安装、注册和配置 Runner，并结合 .gitlab-ci.yml 文件中的作业定义，您可以构建出强大、高效且可靠的自动化开发流程。掌握 Runner 的使用将大大提升您的团队的开发效率和软件交付速度。

滚动至顶部