gitlab runner 安装与配置 – wiki词典

作者： /

GitLab Runner 安装与配置详解

GitLab CI/CD 是一个强大的工具，用于自动化软件开发生命周期中的构建、测试和部署阶段。而 GitLab Runner 则是其核心组成部分，它负责执行 gitlab-ci.yml 文件中定义的作业。本文将详细介绍 GitLab Runner 的安装、注册和配置过程，帮助您为持续集成/持续交付环境做好准备。

1. 引言

GitLab Runner 是一个开源代理，它与 GitLab CI/CD 协同工作，用于执行您项目中的 CI/CD 作业。无论是运行测试、构建 Docker 镜像还是部署应用程序，Runner 都能在各种环境中执行这些任务，并将结果反馈给 GitLab。理解如何正确安装和配置 Runner 对于构建高效可靠的 CI/CD 管道至关重要。

2. 前置条件

在开始安装之前，请确保满足以下条件：

  • 一台主机：用于运行 GitLab Runner 的物理机、虚拟机或 Docker 主机（支持 Linux、Windows、macOS）。
  • GitLab 实例 URL：您的 GitLab 实例地址（例如 https://gitlab.com 或您的自托管实例地址）。
  • GitLab 注册令牌或认证令牌：用于将 Runner 注册到 GitLab 实例。

3. 安装 GitLab Runner

GitLab Runner 支持多种安装方式。这里我们介绍几种常见的方法。

a. Linux (以 Debian/Ubuntu 为例)

通过包管理器安装是 Linux 系统上最推荐的方式。

  1. 添加 GitLab Runner 仓库：
    bash
    curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
    此脚本会自动设置 GitLab Runner 的 APT 仓库。
  2. 安装 GitLab Runner：
    bash
    sudo apt-get update
    sudo apt-get install gitlab-runner
    对于 RHEL/CentOS 系统，您可以使用 yum 或 dnf 命令进行安装。

b. Windows

在 Windows 上，您可以将其作为服务运行。

  1. 下载可执行文件：
    从 GitLab Runner 官方发布页面下载最新的 gitlab-runner-windows-amd64.exe 可执行文件。建议将其重命名为 gitlab-runner.exe 以方便操作。
  2. 创建目录：
    创建一个目录来存放 Runner 文件，例如 C:\GitLab-Runner。
  3. 移动可执行文件：
    将下载的 gitlab-runner.exe 文件移动到 C:\GitLab-Runner 目录中。
  4. 安装并启动服务：
    以管理员身份打开 PowerShell 或命令提示符，导航到 C:\GitLab-Runner 目录，然后运行：
    powershell
    .\gitlab-runner.exe install
    .\gitlab-runner.exe start

c. Docker

通过 Docker 运行 GitLab Runner 是一种灵活且易于管理的方式，尤其适合需要隔离构建环境的场景。

  1. 创建 Docker 数据卷：
    用于持久化 Runner 的配置信息。
    bash
    docker volume create gitlab-runner-config
  2. 运行 GitLab Runner 容器：
    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: 挂载 Docker Socket，允许 Runner 在容器内运行 Docker 命令（实现 Docker-in-Docker）。
    • -v gitlab-runner-config:/etc/gitlab-runner: 挂载之前创建的数据卷，用于存放 Runner 的配置。
    • gitlab/gitlab-runner:latest: 使用最新的 GitLab Runner Docker 镜像。

4. 注册 GitLab Runner

安装完成后，需要将 Runner 注册到您的 GitLab 实例。

a. 获取注册令牌/认证令牌

  1. 登录 GitLab。
  2. 导航到您的项目、群组或实例的 Settings > CI/CD。
  3. 展开 Runners 部分。
  4. 在 “New project runner”（新项目 Runner）、”New group runner”（新群组 Runner）或 “New instance runner”（新实例 Runner）下，您会找到 GitLab 实例 URL 和一个注册令牌 (Registration Token)。
    • 注意：从 GitLab 15.6 开始，建议使用认证令牌 (Authentication Token)。您可以在 GitLab UI 中直接创建 Runner，GitLab 会提供一个认证令牌，此令牌比传统的注册令牌更安全且具有更多管理选项。

b. 执行注册命令

在安装了 GitLab Runner 的机器上打开终端（Windows 为 PowerShell/CMD），或在 Docker 容器中执行命令。

“`bash

对于 Linux/macOS/Windows (如果 gitlab-runner 在 PATH 中)

gitlab-runner register

对于 Docker (在宿主机上执行)

docker run –rm -it -v gitlab-runner-config:/etc/gitlab-runner gitlab/gitlab-runner:latest register
“`

执行注册命令后，您将收到一系列提示：

  • Enter the GitLab instance URL: 输入您的 GitLab 实例 URL (例如 https://gitlab.com/)。
  • Enter the registration token: 输入您从 GitLab UI 获取的注册令牌。如果您使用的是认证令牌，请直接在 GitLab UI 中创建 Runner，然后跳过此手动注册步骤。
  • Enter a description for the runner: 为您的 Runner 提供一个有意义的描述 (例如 “我的 Linux 构建服务器”)。
  • Enter tags for the runner (comma-separated): 输入逗号分隔的标签 (例如 linux,docker,frontend)。标签是 GitLab CI/CD 中将作业路由到特定 Runner 的关键机制。
  • Enter the executor: 选择一个执行器。常见的选项包括 shell、docker、ssh、kubernetes。docker 执行器因其隔离性和可重现性而广泛使用。
  • Enter the default Docker image (e.g. ruby:2.7): (如果选择了 docker 执行器) 指定一个默认的 Docker 镜像 (例如 alpine:latest 或 ubuntu:latest)。

示例 (使用 docker 执行器):

Enter the GitLab instance URL: https://gitlab.com/
Enter the registration token: <您的注册令牌>
Enter a description for the runner: My Docker Runner
Enter tags for the runner (comma-separated): docker,linux
Enter the executor: docker
Enter the default Docker image (e.g. ruby:2.7): alpine:latest
Runner registered successfully. Feel free to start it, but if it's already running it should pick up new configuration automatically.

5. 配置 GitLab Runner

GitLab Runner 的高级配置通过 config.toml 文件进行管理。

a. config.toml 文件

  • 位置：

    • Linux: /etc/gitlab-runner/config.toml
    • Windows: C:\GitLab-Runner\config.toml
    • Docker: 在挂载的数据卷中，例如 gitlab-runner-config/config.toml (在容器内部路径为 /etc/gitlab-runner/config.toml)。

  • 作用：
    此文件包含了 Runner 的所有配置，包括并发设置、执行器类型、缓存、以及每个注册 Runner 的详细信息。您可以通过编辑此文件来微调 Runner 的行为。

b. 常见配置选项

以下是 config.toml 文件中一些常见的配置项示例及其解释：

“`toml
concurrent = 1 # Runner 可以同时运行的最大作业数
check_interval = 0 # Runner 检查新作业的间隔时间 (秒)，0 表示立即检查

[session_server]
session_timeout = 1800 # Session server 超时时间 (秒)

[[runners]] # 每个 [[runners]] 块定义一个注册的 Runner
name = “My Docker Runner” # Runner 的名称
url = “https://gitlab.com/” # GitLab 实例 URL
token = “<您的认证令牌>” # Runner 的认证令牌 (注意：这里是认证令牌，不是注册令牌)
executor = “docker” # 执行器类型

[runners.custom_build_dir] # 自定义构建目录设置
[runners.cache] # 缓存设置
# [runners.cache.s3]
# [runners.cache.gcs]
[runners.docker] # Docker 执行器特有的配置
tls_verify = false # 是否验证 TLS
image = “alpine:latest” # 默认 Docker 镜像
privileged = false # 是否以特权模式运行容器
disable_entrypoint_overwrite = false # 是否禁用 Docker 镜像的 entrypoint 覆盖
oom_kill_disable = false # 是否禁用 OOM kill
disable_cache = false # 是否禁用 Docker 缓存
volumes = [“/cache”] # 挂载的卷
shm_size = 0 # /dev/shm 的大小 (MB)
“`

  • concurrent: 定义了 Runner 可以同时执行的最大作业数量。
  • executor: 指定作业将在何种环境中执行，例如 shell (在 Runner 主机上直接执行)、docker (在 Docker 容器中执行) 或 ssh (通过 SSH 连接到远程服务器执行)。
  • tags: 在 [[runners]] 块中，会列出注册时指定的标签。GitLab CI/CD 通过 .gitlab-ci.yml 文件中的 tags 关键字来匹配并选择合适的 Runner 执行作业。
  • cache: 用于配置作业之间的依赖缓存，可以显著加快 CI/CD 管道的速度。
  • artifacts: 定义了作业产物的处理方式。

每次修改 config.toml 文件后，您需要重启 GitLab Runner 服务以使更改生效。

6. 验证 GitLab Runner

完成安装和注册后，验证 Runner 是否正常工作是最后一步。

a. 在 GitLab UI 中检查状态

  1. 登录 GitLab。
  2. 导航到您的项目、群组或实例的 Settings > CI/CD > Runners。
  3. 您应该能看到您刚刚注册的 Runner，并且其状态显示为“在线 (Online)”（通常是一个绿色的圆点或图标）。

b. 通过 .gitlab-ci.yml 进行测试

在您的 GitLab 项目根目录中创建一个 .gitlab-ci.yml 文件（如果尚未存在），并添加一个简单的测试作业：

“`yaml
stages:
– build

build_job:
stage: build
script:
– echo “Hello from GitLab Runner!”
– echo “This job is running on a runner with tags: $CI_RUNNER_TAGS”
tags:
– docker # 确保这里使用的标签与您注册 Runner 时指定的标签匹配
“`

  1. 将此 .gitlab-ci.yml 文件提交并推送到您的 GitLab 仓库。
  2. GitLab CI/CD 会自动检测到新的提交，并创建一个新的管道。
  3. 导航到项目的 CI/CD > Pipelines 页面，您应该能看到新创建的管道和正在运行的 build_job。
  4. 点击作业，查看其输出日志。如果一切正常，您将看到 “Hello from GitLab Runner!” 和 Runner 的标签信息。

7. 总结

通过本文的详细指导，您应该已经成功安装、注册并配置了 GitLab Runner。GitLab Runner 是实现 CI/CD 自动化的基石，它使得您的开发流程更加高效和可靠。您可以根据项目的具体需求，进一步探索 GitLab Runner 的高级配置选项和不同执行器类型，以构建更复杂的自动化工作流。

希望本文对您有所帮助！

滚动至顶部