本文档基于 GitLab 官方文档整理，详细说明了如何在主流 Linux 发行版上，通过 GitLab 官方仓库安装、升级 GitLab Runner 及其相关组件，并包含了 GPG 签名验证等高级配置说明。

1. 概述

本文档介绍如何使用 GitLab 官方仓库提供的软件包来安装 GitLab Runner。

  • 适用版本：社区版（Free）、高级版（Premium）、旗舰版（Ultimate）
  • 适用部署：GitLab.com、GitLab 自托管实例、GitLab 专属实例

2. 支持的发行版

GitLab 通过 Packagecloud 为以下 Linux 发行版的受支持版本提供软件包。当 Packagecloud 支持新的操作系统发行版时，对应的新 Runner deb 或 rpm 软件包会自动添加。

2.1 基于 Deb 的发行版

发行版 支持的版本
Debian 15 Duke, 14 Forky, 13 Trixie, 12 Bookworm, 11 Bullseye
LinuxMint 22.1 Xia, 22 Wilma, 21.3 Virginia, 21.2 Victoria, 21.1 Vera, 21 Vanessa, 20.3 Una, 20.2 Uma, 20.1 Ulyssa, 20 Ulyana
Raspbian 15 Duke, 14 Forky, 13 Trixie, 12 Bookworm, 11 Bullseye
Ubuntu 25.04 Plucky Puffin, 24.10 Oracular Oriole, 24.04 Lts Noble Numbat, 22.04 Jammy Jellyfish, 20.04 Focal Fossa, 18.04 Lts Bionic Beaver, 16.04 Lts Xenial Xerus

2.2 基于 Rpm 的发行版

发行版 支持的版本
Amazon Linux 2025, 2023, 2022, 2
Red Hat Enterprise Linux 10, 9, 8, 7
Fedora 43, 42, 41, 40
Oracle Linux 10, 9, 8, 7, 6
openSUSE 16.0, 15.6, 15.5, 15.4, 15.3, 15.2, 15.1, 15.0
SUSE Linux Enterprise Server 15.7, 15.6, 15.5, 15.4, 15.3, 15.2, 12.5

说明： - 根据你的具体环境，其他基于 Debian 或 RPM 的衍生发行版（例如 Deepin）也可能受支持，前提是它们拥有兼容的软件包仓库。 - 未在列表中的发行版无法从我们的软件包仓库获取安装包。你可以手动从我们的 S3 存储桶下载 RPM 或 DEB 包进行安装。

3. 安装 GitLab Runner

3.1 添加官方仓库并安装

  1. 添加 GitLab 官方软件仓库： 执行以下命令来添加仓库：

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

  2. 安装 GitLab Runner： 默认情况下，安装时会禁用 skel 目录的使用，以防止出现“No such file or directory”的作业失败错误。

    • 安装最新版本： bash sudo apt install gitlab-runner
    • RHEL 系统的 FIPS 版本：对于需要 FIPS 140-2 合规性的 RHEL 发行版，请使用 gitlab-runner-fips 作为软件包名称。

3.2 安装特定版本

从 gitlab-runner 版本 v17.7.1 开始，当安装非最新特定版本时，必须同时显式安装对应版本的 gitlab-runner-helper-images 软件包。这是由于 apt/apt-get 的限制。

  1. 查看可用的版本： bash apt-cache madison gitlab-runner
  2. 安装特定版本及其对应的辅助镜像包（以 17.7.1 为例）： bash sudo apt install gitlab-runner=17.7.1-1 gitlab-runner-helper-images=17.7.1-1

注意：如果未同时安装相同版本的 gitlab-runner-helper-images，可能会遇到类似以下依赖错误：

The following packages have unmet dependencies:
 gitlab-runner : Depends: gitlab-runner-helper-images (= 17.7.1-1) but 17.8.3-1 is to be installed

完成上述步骤后，Runner 即可启动并与项目一起使用。建议阅读 FAQ 部分以了解常见问题。

4. 辅助镜像包

gitlab-runner-helper-images 软件包包含 GitLab Runner 在执行作业时使用的预构建辅助容器镜像。这些镜像提供了克隆仓库、上传产物和管理缓存所必需的工具。

该软件包包含以下操作系统和架构的辅助镜像：

  • 基于 Alpine 的镜像（最新版）： alpine-arm, alpine-arm64, alpine-riscv64, alpine-s390x, alpine-x86_64, alpine-x86_64-pwsh
  • 基于 Ubuntu 的镜像（24.04）： ubuntu-arm, ubuntu-arm64, ubuntu-ppc64le, ubuntu-s390x, ubuntu-x86_64, ubuntu-x86_64-pwsh

4.1 自动下载辅助镜像

如果宿主机系统上没有特定操作系统和架构组合的辅助镜像，GitLab Runner 会在需要时自动下载所需的镜像。对于未包含在 gitlab-runner-helper-images 包中的架构（例如 loong64），无需手动安装。这确保了 Runner 能够支持更多架构，而无需人工干预。

5. 升级 GitLab Runner

要安装最新版本的 GitLab Runner，请运行：

sudo apt update
sudo apt install gitlab-runner

6. 软件包安装的 GPG 签名

GitLab Runner 项目为软件包安装方式提供两种 GPG 签名。

6.1 仓库元数据签名

用于验证从远程仓库下载的软件包信息是否可信。当你执行 apt-get update 等命令时，会验证此签名。如果验证失败，软件包管理器会拒绝元数据，从而无法从该仓库安装任何软件包。

首次按照上述说明安装时，用于验证的 GPG 公钥会自动安装。未来密钥更新时，现有用户需要手动下载和安装新密钥。

我们在 https://packages.gitlab.com 下的所有项目共用一把密钥。密钥详情可在 Linux 软件包文档中找到，该页面也列出了所有历史密钥。

6.2 软件包签名

仓库元数据签名仅证明版本信息来源于 https://packages.gitlab.com，并不证明软件包本身的完整性。软件包签名则是在构建时对每个软件包进行签名，以验证其来源和完整性。

软件包签名验证在某些基于 Debian/RPM 的发行版中默认启用。要使用此验证，你可能需要调整配置。

6.2.1 RPM 发行版

RPM 格式内置完整的 GPG 签名功能。GitLab Runner 的差异在于： - 应安装的公钥包名为 gpg-pubkey-35dfa027-60ba0235。 - 仓库文件位于 /etc/yum.repos.d/runner_gitlab-runner.repo（稳定版）或 /etc/yum.repos.d/runner_unstable.repo（不稳定版）。 - 可从以下地址导入公钥：https://packages.gitlab.com/runner/gitlab-runner/gpgkey/runner-gitlab-runner-49F16C5CC3A0F81F.pub.gpg。

6.2.2 Debian 发行版

deb 格式官方未包含默认的包签名方法。GitLab Runner 项目使用 dpkg-sig 工具进行签名和验证，此方法仅支持手动验证。 验证步骤： 1. 安装 dpkg-sig： bash apt update && apt install dpkg-sig 2. 下载并导入公钥： bash curl -JLO "https://packages.gitlab.com/runner/gitlab-runner/gpgkey/runner-gitlab-runner-49F16C5CC3A0F81F.pub.gpg" gpg --import runner-gitlab-runner-49F16C5CC3A0F81F.pub.gpg 3. 验证已下载的包： bash dpkg-sig --verify gitlab-runner_amd64.deb - 签名有效会显示 GOODSIG。 - 签名无效或密钥无效会显示 BADSIG。 - 密钥不在密钥环中会显示 UNKNOWNSIG。

6.3 当前 GPG 公钥

用于软件包签名的当前公钥可从以下地址下载：https://packages.gitlab.com/runner/gitlab-runner/gpgkey/runner-gitlab-runner-49F16C5CC3A0F81F.pub.gpg

密钥属性 值
名称 GitLab, Inc.
邮箱 support@gitlab.com
指纹 931D A69C FA3A FEBB C97D AA8C 6C57 C29C 6BA7 5A4E
过期时间 2026-04-28

该密钥也用于对 S3 发布桶 (gitlab-runner-downloads.s3.dualstack.us-east-1.amazonaws.com) 中的 release.sha256 文件进行签名。

6.4 历史 GPG 公钥

过去使用的密钥如下表。对于已撤销的密钥，强烈建议将其从软件包签名验证配置中移除。

序号 密钥指纹 状态 过期日期 下载（仅撤销密钥）
1 3018 3AC2 C4E2 3A40 9EFB E705 9CE4 5ABC 8807 21D4 已撤销 2021-06-08 下载链接
2 09E5 7083 F34C CA94 D541 BC58 A674 BF81 35DF A027 已撤销 2023-04-26 下载链接

7. 故障排除

7.1 错误：作业失败 No such file or directory

有时默认的骨架 (skel) 目录会导致 GitLab Runner 运行作业失败。

默认情况下，安装 GitLab Runner 时创建的 gitlab-runner 用户，其家目录不会使用 skel 中的内容初始化。如果之前安装的 Runner 不是默认行为，可以尝试删除以下点文件：

sudo rm /home/gitlab-runner/.profile
sudo rm /home/gitlab-runner/.bashrc
sudo rm /home/gitlab-runner/.bash_logout

如果需要使用 skel 目录来填充新创建的家目录，必须在安装 Runner 前将 GITLAB_RUNNER_DISABLE_SKEL 变量显式设置为 false：

export GITLAB_RUNNER_DISABLE_SKEL=false; sudo -E apt-get install gitlab-runner

文档来源：GitLab 官方文档 - Install GitLab Runner using the official GitLab repositories 整理日期：2026年1月2日
归档说明：此中文 Markdown 文档为官方英文文档的忠实翻译与整理，用于技术存档与参考。