在容器中运行极狐GitLab Runner

下面将向您介绍如何在 Docker 容器中运行极狐GitLab Runner。

Docker 引擎版本兼容性

一般来说,Docker Engine 的版本和极狐GitLab Runner 容器镜像的版本不需要匹配。 极狐GitLab Runner 镜像应该向后和向前兼容。 然而,为确保您拥有最新的功能和安全更新,您应该使用最新的稳定 Docker 引擎版本

一般极狐GitLab Runner Docker 镜像使用

极狐GitLab Runner Docker 镜像(基于 Ubuntu 或 Alpine Linux)被设计为标准 gitlab-runner 命令周围的包装器,就像极狐GitLab Runner 直接安装在主机上一样。

一般规则是每个极狐GitLab Runner 命令通常会被执行为:

gitlab-runner <runner command and options...>

可以使用以下命令执行:

docker run <chosen docker options...> gitlab/gitlab-runner <runner command and options...>

例如,可以执行以下命令获取最高级别的极狐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:
   15.11.0 (436955cb)

(...)

简而言之,命令的 gitlab-runner 部分由 docker run [docker options] gitlab/gitlab-runner 替代,剩余部分保持与注册文档中描述的内容相一致。 唯一区别是 gitlab-runner 命令是在 Docker 容器中执行的。

安装 Docker 镜像并启动容器

开始之前,请确保已经安装 Docker

如果想在 Docker 容器内运行 gitlab-runner,您需要确保重启容器时配置没有丢失。为此,以下描述两个选项:

请阅读 FAQ,它介绍了您在使用极狐GitLab Runner 时最可能遇到的问题。

  • 如果使用 session_server,您也需要通过向 docker run 命令中添加 -p 8093:8093 暴露端口 8093
  • 如果您想通过 Docker Machine 执行器使用弹性伸缩功能,您还需要挂载 Docker Machine /root/.docker/machine 存储路径:
    • 通过为系统卷挂载添加 -v /srv/gitlab-runner/docker-machine-config:/root/.docker/machine
    • 通过为 Docker 命名的卷添加 -v docker-machine-config:/root/.docker/machine
note此设置将 Docker Daemon 的完全控制权委托给每个极狐GitLab Runner 容器。 如果您在还运行其他负载的 Docker Daemon 中运行极狐GitLab Runner,隔离保证会失效。

选项一:使用本地系统卷挂载,启动 Runner 容器

以下示例使用挂载到 gitlab-runner 容器的配置卷的本地系统。这个卷用于配置资源和其他资源。

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
note在 macOS 上,使用 /Users/Shared 而不是 /srv

选项二:使用 Docker 卷启动 Runner 容器

在这个例子中,您可以使用配置容器挂载您的自定义数据卷。

  1. 创建 Docker 卷:

    docker volume create gitlab-runner-config
    
  2. 使用刚创建的卷启动极狐GitLab Runner 容器:

    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
    
note如果您想设置容器的时区,请在 docker run 命令中使用 --env TZ=<TIMEZONE> 标记。
note对于符合 FIPS 的极狐GitLab Runner 镜像,您需要基于 redhat/ubi8 使用 gitlab/gitlab-runner:ubi-fips 标签。

注册 Runner

最后一步是注册新的 Runner。极狐GitLab Runner 容器在注册之前不会处理任何作业。

升级配置

如果您更改了 config.toml 中的配置,您可能需要重启 Runner 使更改生效。 请确保重启整个容器,而不是使用 gitlab-runner restart 命令:

docker restart gitlab-runner

升级版本

拉取最新版本(或者特定标签):

docker pull gitlab/gitlab-runner:latest

停止并移除现存的容器:

docker stop gitlab-runner && docker rm 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
note您挂载数据卷时使用的方法需要和您最开始使用的方法一致 (-v /srv/gitlab-runner/config:/etc/gitlab-runner--volumes-from gitlab-runner-config)。

读取极狐GitLab Runner 日志

当极狐GitLab Runner 作为前台任务(不论是本地安装的二进制文件或 Docker 容器内部)被启动时,日志会被打印为标准输出。当极狐GitLab Runner 作为系统服务被启动时(例如,使用 Systemd),大多数情况下的日志都是通过 Syslog 或其他系统记录机制进行记录的。

极狐GitLab Runner 作为基于服务的 Docker 被启动,因为 gitlab-runner ... 命令是容器的主要进程,可以使用 docker logs 命令读取日志。

例如,如果使用以下命令启动极狐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

您可以使用以下命令获取日志:

docker logs gitlab-runner

其中 gitlab-runner 是容器的名称,可以在第一个命令中输入 --name gitlab-runner 进行设置。

关于处理容器日志的更多信息,请参见 Docker 文档页

安装受信任的 SSL 服务器证书

如果您的极狐GitLab CI 服务器使用自签名 SSL 证书,那么您应该确保极狐GitLab CI 服务器证书受到极狐GitLab Runner 容器的信任,使其能够通信。

gitlab/gitlab-runner 镜像被配置为在 /etc/gitlab-runner/certs/ca.crt 中寻找受信任的 SSL 证书,也可以使用 -e "CA_CERTIFICATES_PATH=/DIR/CERT" 配置选项进行更改。

ca.crt 文件复制到数据卷(或容器)上的 certs 目录中。 ca.crt 文件应包含您希望极狐GitLab Runner 信任的所有服务器的根证书。 极狐GitLab Runner 容器在启动时导入 ca.crt 文件,因此如果您的容器已经在运行中,您可能需要重新启动它使更改生效。

Docker 镜像

以下多平台 Docker 镜像可用:

  • 基于 Ubuntu 的 gitlab/gitlab-runner:latest
  • 基于 Alpine 的空间更小的 gitlab/gitlab-runner:alpine。 (~160/350 MB Ubuntu vs ~45/130 MB Alpine 压缩文件/解压缩文件)。

关于 Ubuntu 和 Alpine 镜像的构建说明,请参见极狐GitLab Runner 源。

创建极狐GitLab Runner Docker 镜像

截至极狐GitLab Runner 16.1,基于 Alpine 的极狐GitLab Runner Docker 镜像使用的是 Alpine 3.12.0。然而,在极狐GitLab 仓库中可以使用它之前,您可以升级镜像的操作系统。

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

  1. 创建 alpine-upgrade/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 镜像。

    GITLAB_RUNNER_IMAGE_TYPE=gitlab-runner GITLAB_RUNNER_IMAGE_TAG=alpine-v16.1.0 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 镜像。

    GITLAB_RUNNER_IMAGE_TYPE=gitlab-runner-helper GITLAB_RUNNER_IMAGE_TAG=x86_64-v16.1.0 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
    
noteIBM Z 镜像不包括 docker-machine 依赖项,因为 Linux s390x 或 Linux ppc64le 平台没有进行维护。

SELinux

一些发行版(CentOS、Red Hat、Fedora)默认使用 SELinux 加强底层系统的安全。

您在处理这种配置时一定要特别注意。

  1. 如果您想使用 Docker 执行器运行容器中的构建,您需要访问 /var/run/docker.sock。 然而,如果 SELinux 处于强制模式,当您访问 /var/run/docker.sock 时会出现 Permission denied 错误。 安装 selinux-dockersock 可以解决这个问题。
  2. 确保在主机上创建了持久目录:mkdir -p /srv/gitlab-runner/config
  3. 在卷上使用 :Z 运行 Docker。
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 Runner 容器镜像支持生命周期

我们将遵循用于创建极狐GitLab Runner 容器镜像的基本发行版(Ubuntu、Alpine、Red Hat Universal Base Image)的支持生命周期。

基本发行版的发布结束日期不一定与极狐GitLab 的主要发布周期一致。这意味着我们将停止发布次要版本中的极狐GitLab Runner 容器镜像版本。这可以确保我们不发布上游发行版不再更新的镜像。

容器镜像和发布日期结束

基本容器 基本容器版本 厂商 EOL 日期 极狐GitLab EOL 日期
Ubuntu 20.04 2030-04-09 2030-04-22
Alpine 3.12 2022-05-01 2023-05-22
Alpine 3.13 2022-11-01 2023-05-22
Alpine 3.14 2023-05-01 2023-05-22
Alpine 3.15 2023-11-01 2023-11-22
Alpine 3.16 2024-05-23 2024-06-22
Alpine 3.17 2024‑11‑22 2024-12-22
Alpine 3.18 2025‑05‑09 2025-05-22
Red Hat Universal Base Image 8 8.7-1054 2024-05-31 2024-06-22