在 Docker 容器中运行 GitLab Runner

本文档完整翻译并整理了 GitLab 官方关于在 Docker 容器中运行 GitLab Runner 的安装与配置指南，内容涵盖从基础安装、配置、升级到高级主题如 SSL 证书和 SELinux 配置的所有细节。

您可以在 Docker 容器中运行 GitLab Runner 来执行 CI/CD 任务。GitLab Runner Docker 镜像包含了运行 GitLab Runner 和在容器中执行 CI/CD 任务所需的所有依赖。

GitLab Runner Docker 镜像基于 Ubuntu 或 Alpine Linux。它们封装了标准的 gitlab-runner 命令，类似于在主机上直接安装 GitLab Runner。

  • 层级（Tier）： Free, Premium, Ultimate
  • 产品线（Offering）： GitLab.com, GitLab Self-Managed, GitLab Dedicated

gitlab-runner 命令在 Docker 容器中运行。此设置将 Docker 守护进程的完全控制权委托给每个 GitLab Runner 容器。其效果是，如果您在一个也运行其他负载的 Docker 守护进程中运行 GitLab Runner，则隔离保证会被破坏。

在此设置中，您运行的每个 GitLab Runner 命令都有一个等效的 docker run 命令，如下所示：

  • Runner 命令：gitlab-runner <runner command and options...>
  • Docker 命令：docker run <chosen docker options...> gitlab/gitlab-runner <runner command and options...>

例如，要获取 GitLab Runner 的顶级帮助信息，请将命令中的 gitlab-runner 部分替换为 docker run [docker options] gitlab/gitlab-runner，如下所示：

docker run --rm -t -i gitlab/gitlab-runner --help

NAME:
   gitlab-runner - a GitLab Runner

USAGE:
   gitlab-runner [global options] command [command options] [arguments...]

VERSION:
   17.9.1 (bbf75488)

...

🛠 Docker 引擎版本兼容性

Docker 引擎和 GitLab Runner 容器镜像的版本不必匹配。GitLab Runner 镜像具有向后和向前兼容性。为确保您拥有最新的功能和安全性更新，应始终使用最新的稳定版 Docker Engine。

1 安装 Docker 镜像并启动容器

1.1 前提条件

  • 已安装 Docker。
  • 已阅读 FAQ，了解 GitLab Runner 中的常见问题。

1.2 安装与启动步骤

  1. 使用 docker pull gitlab/gitlab-runner:<version-tag> 命令下载 gitlab-runner Docker 镜像。有关可用版本标签的列表，请参阅 GitLab Runner 标签。

  2. 使用 docker run -d [options] <image-uri> <runner-command> 命令运行 gitlab-runner Docker 镜像。

  3. 在 Docker 容器中运行 gitlab-runner 时，请确保配置在容器重启时不会丢失。挂载一个持久化卷来存储配置。该卷可以挂载在以下任一位置：

    • /etc/gitlab-runner，用于配置。
    • /home/gitlab-runner，用于数据缓存和构建工件（如果使用 docker 执行器）。

  4. （可选）如果使用 session_server，通过在你的 docker run 命令中添加 -p 8093:8093 来暴露端口 8093。

  5. （可选）要使用 Docker Machine 执行器进行自动扩缩容，请通过添加卷挂载到你的 docker run 命令来挂载 Docker Machine 存储路径（/root/.docker/machine）：

    • 对于系统卷挂载，添加 -v /srv/gitlab-runner/docker-machine-config:/root/.docker/machine
    • 对于 Docker 命名卷，添加 -v docker-machine-config:/root/.docker/machine

  6. 注册一个新的 Runner。GitLab Runner 容器必须注册后才能接收作业。

一些可用的配置选项包括：

  • 使用 --env TZ=<TIMEZONE> 标志设置容器的时区。参见可用时区列表。
  • 如需基于 redhat/ubi9-micro 的 FIPS 兼容 GitLab Runner 镜像，请使用 gitlab/gitlab-runner:ubi-fips 标签。
  • 安装可信的 SSL 服务器证书。

1.3 挂载本地系统卷

要使用本地系统作为配置卷和其他挂载到 gitlab-runner 容器中的资源，请执行以下操作：

  1. （可选）在 MacOS 系统中，/srv 默认不存在。请为设置创建 /private/srv 或另一个私有目录。

  2. 运行以下命令，并根据需要进行修改： bash docker run -d --name gitlab-runner --restart always \ -v /srv/gitlab-runner/config:/etc/gitlab-runner \ -v /var/run/docker.sock:/var/run/docker.sock \ gitlab/gitlab-runner:latest

1.4 挂载 Docker 命名卷

要使用配置容器来挂载您的自定义数据卷，请执行以下操作：

  1. 创建 Docker 卷： 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

2 更新 Runner 配置

在 config.toml 中更改 runner 配置后，通过使用 docker stop 和 docker run 重启容器来应用更改。

3 升级 Runner 版本

3.1 前提条件

  • 必须使用与最初挂载数据卷相同的方法（-v /srv/gitlab-runner/config:/etc/gitlab-runner 或 -v gitlab-runner-config:/etc/gitlab-runner）。

3.2 升级步骤

  1. 拉取最新版本（或特定标签）： bash docker pull gitlab/gitlab-runner:latest
  2. 停止并移除现有容器： bash docker stop gitlab-runner && docker rm gitlab-runner
  3. 按照最初的方式启动容器： 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 查看 Runner 日志

日志文件的位置取决于启动 Runner 的方式：

  • 作为前台任务启动时（无论是作为本地安装的二进制文件还是在 Docker 容器中），日志会打印到 stdout。
  • 作为系统服务启动时（例如使用 systemd），日志可通过系统日志机制（如 Syslog）获取。
  • 作为基于 Docker 的服务启动时，使用 docker logs 命令查看日志，因为 gitlab-runner ... 命令是容器的主进程。

例如，如果您使用以下命令启动一个容器，并将其名称设置为 gitlab-runner：

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

要查看其日志，请运行以下命令（将 gitlab-runner 替换为您的容器名称）：

docker logs gitlab-runner

有关处理容器日志的更多信息，请参阅 Docker 文档中的 docker container logs。

5 安装可信的 SSL 服务器证书

如果您的 GitLab CI/CD 服务器使用自签名 SSL 证书，请确保您的 Runner 容器信任 GitLab CI 服务器的证书。这可以防止通信失败。

5.1 前提条件

  • 您的 ca.crt 文件应包含您希望 GitLab Runner 信任的所有服务器的根证书。

5.2 安装步骤

  1. （可选）gitlab/gitlab-runner 镜像在 /etc/gitlab-runner/certs/ca.crt 中查找可信 SSL 证书。要更改此行为，请使用 -e "CA_CERTIFICATES_PATH=/DIR/CERT" 配置选项。
  2. 将您的 ca.crt 文件复制到数据卷（或容器）上的 certs 目录中。
  3. （可选）如果您的容器已在运行，请重启它以在启动时导入 ca.crt 文件。

6 Docker 镜像

在 GitLab Runner 18.8.0 中，基于 Alpine 的 Docker 镜像使用 Alpine 3.21。提供以下多平台 Docker 镜像：

  • gitlab/gitlab-runner:latest 基于 Ubuntu，大小约为 800 MB。
  • gitlab/gitlab-runner:alpine 基于 Alpine，大小约为 460 MB。

有关 Ubuntu 和 Alpine 镜像的可能构建说明，请参阅 GitLab Runner 源码。

6.1 创建自定义 Runner Docker 镜像

您可以在 GitLab 存储库提供更新之前，升级镜像的操作系统。

前提条件

  • 您未使用 IBM Z 镜像，因为它不包含 docker-machine 依赖项。该镜像不为 Linux s390x 或 Linux ppc64le 平台维护。有关当前状态，请参阅 issue 26551。

为最新 Alpine 版本构建 gitlab-runner Docker 镜像

  1. 创建 alpine-upgrade/Dockerfile： ```dockerfile ARG GITLAB_RUNNER_IMAGE_TYPE ARG GITLAB_RUNNER_IMAGE_TAG FROM gitlab/${GITLAB_RUNNER_IMAGE_TYPE}:${GITLAB_RUNNER_IMAGE_TAG}

    RUN apk update RUN apk upgrade 2. 创建升级后的 `gitlab-runner` 镜像：bash GITLAB_RUNNER_IMAGE_TYPE=gitlab-runner \ GITLAB_RUNNER_IMAGE_TAG=alpine-v17.9.1 \ docker build -t $GITLAB_RUNNER_IMAGE_TYPE:$GITLAB_RUNNER_IMAGE_TAG \ --build-arg GITLAB_RUNNER_IMAGE_TYPE=$GITLAB_RUNNER_IMAGE_TYPE \ --build-arg GITLAB_RUNNER_IMAGE_TAG=$GITLAB_RUNNER_IMAGE_TAG \ -f alpine-upgrade/Dockerfile alpine-upgrade 3. 创建升级后的 `gitlab-runner-helper` 镜像：bash GITLAB_RUNNER_IMAGE_TYPE=gitlab-runner-helper \ GITLAB_RUNNER_IMAGE_TAG=x86_64-v17.9.1 \ docker build -t $GITLAB_RUNNER_IMAGE_TYPE:$GITLAB_RUNNER_IMAGE_TAG \ --build-arg GITLAB_RUNNER_IMAGE_TYPE=$GITLAB_RUNNER_IMAGE_TYPE \ --build-arg GITLAB_RUNNER_IMAGE_TAG=$GITLAB_RUNNER_IMAGE_TAG \ -f alpine-upgrade/Dockerfile alpine-upgrade ```

7 在容器中使用 SELinux

某些发行版（如 CentOS、Red Hat 和 Fedora）默认使用 SELinux（安全增强型 Linux）来增强底层系统的安全性。

请谨慎使用此配置。

7.1 前提条件

  • 要使用 Docker 执行器在容器中运行构建，Runner 需要访问 /var/run/docker.sock。
  • 如果在强制模式下使用 SELinux，请安装 selinux-dockersock 以防止 Runner 访问 /var/run/docker.sock 时出现 Permission denied 错误。

7.2 配置步骤

  1. 在主机上创建一个持久化目录： bash mkdir -p /srv/gitlab-runner/config
  2. 在卷上使用 :Z 标志运行 Docker： 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:Z \ gitlab/gitlab-runner:latest

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