我之前也跟你一样，在GitLab官方文档里翻来翻去没找到清晰的执行器配置步骤，踩了不少坑，现在给你整理一套实用的流程，涵盖最常用的几种执行器设置：

一、先搞定Runner的注册（核心步骤） #

不管选哪种执行器，注册都是第一步，执行以下命令启动注册流程：

gitlab-runner register

跟着提示一步步输入：

• GitLab实例地址：比如https://gitlab.com/或者你的私有实例地址
• Runner令牌：在GitLab项目的「Settings → CI/CD → Runners」里获取
• Runner描述：随便填个好认的名字，比如「Docker Build Runner」
• Runner标签：用来指定哪些CI任务用这个Runner，比如docker,build
• 执行器选择：这里选你需要的类型（shell/docker/kubernetes等），选完后会有对应额外配置项

二、常用执行器的详细配置 #

如果已经注册了Runner，想修改执行器或者调整配置，找到Runner的配置文件：

• Linux：/etc/gitlab-runner/config.toml
• macOS：~/.gitlab-runner/config.toml
• Windows：C:\GitLab-Runner\config.toml

修改后记得重启Runner服务生效：gitlab-runner restart（Linux/macOS），Windows可以在服务管理器里重启「GitLab Runner」。

1. Shell 执行器（最简单的本地执行） #

适合快速测试或者依赖本地环境的任务，配置要点：

• 注册时选shell，不需要额外配置
• 确保Runner运行用户（比如Linux下的gitlab-runner）有足够权限：能访问项目目录、执行脚本、安装依赖
• 示例配置片段：

[[runners]]
  name = "Local Shell Runner"
  url = "https://your-gitlab-instance.com/"
  token = "your-runner-token"
  executor = "shell"
  [runners.shell]
    shell = "bash" # 可选，系统会自动适配，比如Windows用powershell

⚠️ 注意：Shell执行器没有环境隔离，多个任务会共享本地环境，容易出现依赖冲突，生产环境尽量少用。

2. Docker 执行器（最常用的隔离环境） #

适合标准化CI/CD流程，每个任务在独立Docker容器中运行，配置要点：

• 注册时选docker，然后输入默认镜像（比如node:18、python:3.11）
• 如果需要构建Docker镜像，要开启privileged或者挂载Docker套接字
• 示例配置片段：

[[runners]]
  name = "Docker Build Runner"
  url = "https://your-gitlab-instance.com/"
  token = "your-runner-token"
  executor = "docker"
  [runners.docker]
    tls_verify = false
    image = "ubuntu:22.04" # 默认镜像，任务里可以覆盖
    privileged = true # 开启Docker-in-Docker（DIND），用于构建镜像
    volumes = ["/cache", "/var/run/docker.sock:/var/run/docker.sock"] # 挂载缓存和Docker套接字
    shm_size = 256m # 可选，增大共享内存，避免部分任务内存不足
  [runners.cache]
    Type = "s3" # 可选，用S3或GCS存缓存，加速任务
    Path = "cache"
    Shared = true

💡 小技巧：如果不想开privileged，可以在.gitlab-ci.yml中添加services: [docker:dind]来实现DIND。

3. Kubernetes 执行器（集群动态扩容） #

适合Kubernetes集群环境，Runner会自动创建Pod来运行CI任务，用完自动销毁，配置要点：

• 注册时选kubernetes，需要提前在K8s中创建Service Account，给Runner足够权限
• 示例配置片段：

[[runners]]
  name = "K8s Runner"
  url = "https://your-gitlab-instance.com/"
  token = "your-runner-token"
  executor = "kubernetes"
  [runners.kubernetes]
    host = "" # 留空自动用K8s内部API地址
    image = "alpine:latest" # 默认Pod镜像
    namespace = "gitlab-runner" # Runner所在的K8s命名空间
    service_account = "gitlab-runner-sa" # 绑定的Service Account，需有权限创建Pod/PVC
    privileged = false
    [runners.kubernetes.volumes]
      cache = { type = "persistentVolumeClaim", claim_name = "runner-cache-pvc", mount_path = "/cache" }

⚠️ 注意：要确保Service Account有edit权限或者更细粒度的权限，避免权限不足导致Pod创建失败。

三、验证配置是否生效 #

1. 查看Runner状态：gitlab-runner status，确保显示Running
2. 去GitLab项目的「CI/CD → Runners」页面，看Runner是否标记为「在线」
3. 跑个测试任务，比如在.gitlab-ci.yml里加：

test-runner:
  script:
    - echo "Runner works!"
    - # 对应执行器的测试命令，比如Docker执行器可以加`docker --version`

如果任务成功执行，说明配置没问题。

内容的提问来源于stack exchange，提问作者Karl Morrison