官方的安装指南链接如下：

• 官方版：Install GitLab Runner
• 中文版：安装 GitLab Runner

官方指南中使用Docker的指引如下：

• 官方版：Run GitLab Runner in a container
• 中文版：在 Docker 容器中运行极狐 GitLab Runner

本教程使用Docker Compose配置GitLab Runner。

创建项目工作目录

在一个合适的位置创建一个目录用于存放gitlab-runner项目的数据，如：

mkdir /opt/gitlab-runner

创建docker-compose.yaml

在项目根目录下创建docker-compose.yaml文件，内容如下

docker-compose.yaml

services:
  gitlab-runner:
    image: gitlab/gitlab-runner:alpine3.21-v18.2.1 # 取保镜像版本与gitlab版本一致，此处均为v18.2.1版本
    container_name: gitlab-runner # 容器名
    restart: always # 始终重启
    privileged: true # 非常重要。这赋予容器几乎与宿主机相同的权限，这是为了在容器内能够运行Docker(Docker-in-Docker, dind)所必需的。
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock # 必须，将宿主机的Docker套接字挂载到容器内，使容器内的 Runner 可以启动和管理其他容器
      - ./config:/etc/gitlab-runner # 将配置数据持久化到宿主机，避免容器重启后注册信息丢失
      - /opt/cache:/opt/cache # 缓存目录，可以为后续的runner执行器提供本地缓存

创建完成后，暂时不启动，主要是先确定好配置文件的挂载目录，此处为./config，下一步我们要先注册Runner生成配置文件。

获取Runner身份验证令牌

注册Runner需要先获取一个Runner身份验证令牌。

身份令牌可以在你的GitLab站点中获取，按需要创建实例、群组或项目级别的 Runner。以实例级Runner为例：

• 在管理员界面下，在侧边栏中找到CI/CD->Runners页面，点击Create instance runner按钮。
• 创建页面如下，按需设置后点击Create runner创建。
  • Tags用于指定哪些任务可以使用此Runner，需要Job中添加对应tag。不需要可不设置，勾选Run untagged jobs即可；
  • Runner description用于对该Runner添加一个简短的描述，可用于区分不同用途，按需设置；
  • Paused用于设置该Runner接收到新任务时，是否停止当前任务；
  • Protected用于设置是否只在受保护分支上使用该Runner；
  • Maximum job timeout用于设置Job的超时时间，不设置默认1小时。
• 创建后可看到系统给出的runner authentication token，复制该token备用。

注册Runner

使用具有正确配置卷挂载的短生命周期gitlab-runner容器来注册。

在项目根目录下执行以下命令，其中：

• 挂载目录及镜像与docker-compose.yaml保持一致
• --network gitlab_default命令用于当在同一Docker环境下运行注册时，添加GitLab容器的默认网络来保证GitLab配置的域名可以被此处的短生命周期gitlab-runner容器正确访问。若您以对GitLab容器中配置的域名做了正常的代理，或直接使用ip:port，保证网络可访问时，可不加此配置。

% docker run --rm -it --network gitlab_default -v ./config:/etc/gitlab-runner gitlab/gitlab-runner:alpine3.21-v18.2.1 register
Runtime platform                                    arch=arm64 os=linux pid=7 revision=cc489270 version=18.2.1
Running in system-mode.

执行成功后，按以下步骤回答几个问题即可，注意其中：

• GitLab instance URL为后续该Runner请求任务的地址，如GitLab中配置的域名可访问，则用域名，否则用可访问的ip:port也可以

┌  Enter the GitLab instance URL (for example, https://gitlab.com/):
│  http://your_gitlab_hostname or your_gitlab_ip_with_port
│
◇  Enter the registration token:
│  glrt-mWPWkvrqHHDYr3N-hlUPWW86MQp0OjEKdToxCw.01.121tebxtz
│
◇  Verifying runner... is valid                        correlation_id=01K3ZD9XERQE20DDY62VDXFF4C runner=mWPWkvrqH
◇  Enter a name for the runner. This is stored only in the local config.toml file:
│  [4a21f7303842]: MainRunner
│
◇  Enter an executor: docker+machine, kubernetes, docker-autoscaler, custom, shell, virtualbox, docker, docker-windows, instance, ssh, parallels:
│  docker
│
◇  Enter the default Docker image (for example, ruby:3.3):
│  alpine:3.21
│
◇  Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!
│
└  Configuration (with the authentication token) was saved in "/etc/gitlab-runner/config.toml"

注册成功后将生成config.toml配置文件，在主机的根目录中位置为./config/config.toml，文件内容大致如下：

config.toml

concurrent = 1
check_interval = 0
shutdown_timeout = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "MainRunner"
  url = "http://your_gitlab_hostname_or_ip_with_port"
  id = 1
  token = "glrt-mWPWkvrqHHDYr3N-hlUPWW86MQp0OjEKdToxCw.01.121tebxtz"
  token_obtained_at = 2025-08-31T06:33:46Z
  token_expires_at = 0001-01-01T00:00:00Z
  executor = "docker"
  [runners.cache]
    MaxUploadedArchiveSize = 0
    [runners.cache.s3]
    [runners.cache.gcs]
    [runners.cache.azure]
  [runners.docker]
    tls_verify = false
    image = "alpine:3.21"
    privileged = false
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    volumes = ["/cache"]
    shm_size = 0
    network_mtu = 0

可能的问题：

• 问题 1

  ERROR: Verifying runner... client error correlation_id= runner=mWPWkvrqH status=only http or https scheme supported

  输入GitLab实例URL时，没有添加http://或https://
• 问题 2

  ERROR: Verifying runner... failed                   correlation_id= runner=mWPWkvrqH status=couldn't execute POST against http://your_gitlab_hostname/api/v4/runners/verify: Post "http://your_gitlab_hostname/api/v4/runners/verify": dial tcp: lookup your_gitlab_hostname on 127.0.0.11:53: no such host

  • 检查输入的URL中的域名，确保是否正确
  • 检查--network指定的网络是否为GitLab容器所在的网络

启动GitLab Runner

此时确保项目根目录下存在./config/config.toml文件，并且其中的token为已注册状态。

在项目根目录下执行以下命令启动GitLab Runner：

docker-compose up -d

运行成功后，在GitLab的Runners页面即可看到Online状态的Runner：

若是使用GitLab容器网络来确保网络连通性的，需在docker-compose.yaml中添加网络配置：

services:
  gitlab-runner:
    image: gitlab/gitlab-runner:alpine3.21-v18.2.1 # 取保镜像版本与gitlab版本一致，此处均为v18.2.1版本
    container_name: gitlab-runner # 容器名
    restart: always # 始终重启
    privileged: true # 非常重要。这赋予容器几乎与宿主机相同的权限，这是为了在容器内能够运行Docker(Docker-in-Docker, dind)所必需的。
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock # 必须，将宿主机的Docker套接字挂载到容器内，使容器内的 Runner 可以启动和管理其他容器
      - ./config:/etc/gitlab-runner # 将配置数据持久化到宿主机，避免容器重启后注册信息丢失
      - /opt/cache:/opt/cache # 缓存目录，可以为后续的runner执行器提供本地缓存
    networks:
      - gitlab_default

networks:
  gitlab_default:
    name: gitlab_default # 显式命名网络（避免项目前缀）
    external: true # 明确声明这是外部网络

测试GitLab Runner

可参考官方指引来创建空项目进行测试：

• Tutorial: Create and run your first GitLab CI/CD pipeline
• 教程：创建并运行你的第一个极狐 GitLab CI/CD 流水线