GitLab Runner Docker镜像文档

镜像概述

GitLab Runner是GitLab CI/CD的核心组件，作为代理程序负责在各种环境中执行自动化作业。该Docker镜像封装了GitLab Runner运行时环境，可快速部署并集成到GitLab CI/CD流水线中，实现代码构建、测试和部署的自动化流程。

核心功能与特性

多环境支持

• 支持多种执行器（Executor）：Docker、Shell、Kubernetes、VirtualBox、Parallels等，适配不同技术栈需求。

高效作业执行

• 支持并行执行多个作业，提升CI/CD流水线吞吐量。
• 支持作业优先级管理，确保关键任务优先执行。

安全与隔离

• 作业运行环境隔离，避免不同项目或作业间的干扰。
• 支持使用私有Docker镜像仓库，确保依赖拉取安全。

灵活配置管理

• 通过标签（Tags）管理Runner，实现作业与Runner的精准匹配。
• 支持自定义构建目录、缓存路径和超时设置。

扩展能力

• 支持Runner集群部署，通过分布式架构应对大规模作业需求。
• 集成第三方工具（如Docker-in-Docker、缓存服务），扩展功能边界。

使用场景与适用范围

代码构建与编译

• 自动化编译源代码（如Java、Go、Python项目），生成可执行文件或部署包。

自动化测试

• 执行单元测试、集成测试、E2E测试，生成测试报告并反馈结果。

持续部署

• 将通过测试的代码自动部署到开发、测试或生产环境。

定时任务与批量处理

• 执行定时代码扫描、数据备份、日志清理等周期性任务。

多项目共享

• 作为共享Runner为多个GitLab项目提供CI/CD服务，降低维护成本。

使用方法与配置说明

前提条件

• 已安装Docker引擎（20.10+版本推荐）。
• 可访问GitLab实例（自托管或GitLab.com），并获取Runner注册令牌（Registration Token）。

基本使用步骤

1. 启动GitLab Runner容器

使用以下命令启动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

参数说明：

• -v /srv/gitlab-runner/config:/etc/gitlab-runner：挂载配置目录，持久化Runner配置。
• -v /var/run/docker.sock:/var/run/docker.sock：如需使用Docker执行器，需挂载Docker套接字。

2. 注册Runner到GitLab

进入容器并执行注册命令：

docker exec -it gitlab-runner gitlab-runner register

根据提示输入以下信息：

• GitLab实例URL（如[***]或自托管GitLab地址）
• 注册令牌（从GitLab项目/群组设置 > CI/CD > Runners获取）
• Runner描述（自定义名称）
• Runner标签（如docker,linux，用于匹配CI/CD作业）
• 执行器类型（如docker）
• （如选择Docker执行器）默认Docker镜像（如alpine:latest）

3. 验证Runner状态

注册完成后，在GitLab的CI/CD设置页面可查看已注册的Runner，状态应为"在线"。

高级配置

环境变量配置

通过环境变量自定义Runner行为，启动容器时添加-e参数：

示例：通过环境变量自动注册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 \
  -e CI_SERVER_URL=[***] \
  -e RUNNER_REGISTRATION_TOKEN=ABC123xyz \
  -e RUNNER_NAME=auto-registered-runner \
  -e RUNNER_TAG_LIST=docker,linux \
  -e RUNNER_EXECUTOR=docker \
  -e DOCKER_IMAGE=alpine:latest \
  gitlab/gitlab-runner:latest

docker-compose配置

使用docker-compose.yml管理Runner部署：

version: '3.8'
services:
  gitlab-runner:
    image: gitlab/gitlab-runner:latest
    container_name: gitlab-runner
    restart: always
    volumes:
      - /srv/gitlab-runner/config:/etc/gitlab-runner
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - CI_SERVER_URL=[***]
      - RUNNER_REGISTRATION_TOKEN=ABC123xyz
      - RUNNER_NAME=compose-runner
      - RUNNER_TAG_LIST=docker,compose
      - RUNNER_EXECUTOR=docker
      - DOCKER_IMAGE=ubuntu:22.04

启动命令：docker-compose up -d

配置文件说明

Runner配置文件位于容器内/etc/gitlab-runner/config.toml，可通过宿主机挂载目录（如/srv/gitlab-runner/config/config.toml）编辑。主要配置项包括：

• concurrent：最大并行作业数
• check_interval：Runner检查新作业的间隔（秒）
• [[runners]]：Runner实例配置，包含名称、URL、令牌、执行器设置等

示例配置片段：

concurrent = 4
check_interval = 0

[[runners]]
  name = "my-docker-runner"
  url = "[***]"
  token = "runner-token-here"
  executor = "docker"
  [runners.docker]
    tls_verify = false
    image = "alpine:latest"
    privileged = false
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    volumes = ["/cache"]
    shm_size = 0
  [runners.cache]
    Insecure = false

维护与更新

更新Runner镜像

docker stop gitlab-runner
docker rm gitlab-runner
docker pull gitlab/gitlab-runner:latest
# 重新启动容器（使用原挂载卷保持配置）
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

查看Runner日志

docker logs -f gitlab-runner

取消注册Runner

docker exec -it gitlab-runner gitlab-runner unregister --name my-docker-runner