CICD基础 -- gitlab-runner 之 executor 字段解析

gitlab-runner register --executor XXX 是在告诉 GitLab Runner：
“以后我拿到 CI Job，要用哪种方式、在哪个环境里执行这些脚本。”

常见 executor 类型含义

现在场景密切相关的，按实战优先级排。

1. --executor docker

含义：

Runner 收到 Job 后，通过 Docker 启动一个新的容器 来执行 .gitlab-ci.yml 里的脚本。

特点：

• 每个 Job 一个干净容器，跑完就销毁，环境可复现。
• 所有构建依赖封到镜像里（如 alpine:3.19、gcc:13、python:3.12）。
• 非常适合你现在这种：gitlab-runner 本身也是 Docker 容器 + 挂宿主机 docker.sock 的模式。

现在的架构是：

1. gitlab-runner 以 Docker 容器形式跑。

2. 它通过挂载 /var/run/docker.sock 去控制宿主机 Docker。

3. 当有 Job：

   • Runner 容器里 Runner 进程 调用宿主机 Docker → 起一个“执行 Job 的容器”（比如 alpine:3.19）→ 在里面跑 script:。

所以注册时用：

--executor "docker"
--docker-image "alpine:3.19"

2. --executor shell

含义：

直接在 Runner 所在机器的 shell 里执行脚本。

特点：

• 不起新容器，Job 就是直接在宿主机跑 bash / sh 命令。
• 轻巧，但几乎没有隔离，要自己保证环境和安全。

适合：

• 只给自己用，且机器环境简单可控。
• 不太适合你目前“用 Docker 包 Runner”的架构（那样已经绕一层了，不如直接 docker executor）。

3. --executor kubernetes

含义：

Runner 每接一个 Job，就在 K8s 集群里起一个 Pod 来跑。

特点：

• 云原生、大规模、多租户、弹性扩缩专用。
• 如果你没有现成 K8s，现在可以先完全不用考虑。

4. --executor ssh

含义：

Runner 通过 SSH 登录到一台远程机器，在那台机器上执行脚本。

一般不推荐，用得少，管理和安全都麻烦。

5. --executor custom / autoscaler / instance（高级用）

• 给需要自己写执行逻辑、或用 Fleeting/Taskscaler 做弹性伸缩的大型环境用。
• 目前我们先不展开，你要的话可以单独讲一轮。

实战

1. 启动 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:alpine
   

2. 在 Runner 容器里注册（关键点是 --executor docker）：

   docker exec -it gitlab-runner gitlab-runner register \
     --url "http://你的-gitlab-地址" \
     --registration-token "你的token" \
     --executor "docker" \
     --description "docker-runner" \
     --tag-list "docker" \
     --docker-image "alpine:3.19"
   

3. 项目 .gitlab-ci.yml：

   stages: [test]
   
   hello:
     stage: test
     tags: ["docker"]
     image: alpine:3.19
     script:
       - echo "Hello from GitLab CI (docker executor)!"
   

参数详细解析

-v /srv/gitlab-runner/config:/etc/gitlab-runner

有三个要点：

1. 左边 /srv/gitlab-runner/config 是“目录”，不是文件。
2. 可以是空目录，不需要提前写任何内容。
3. 推荐你手动建一下，更可控。

1. 必须是目录，映射到 Runner 的配置目录

容器内的 /etc/gitlab-runner 是 gitlab-runner 用来存放配置的目录（里面会生成 config.toml 等文件）。

-v /srv/gitlab-runner/config:/etc/gitlab-runner 的意思是：

“把宿主机上的 /srv/gitlab-runner/config 当作容器里的 /etc/gitlab-runner。”

所以：

• /srv/gitlab-runner/config 在宿主机上要当成一个目录来用。
• 容器启动后、执行 gitlab-runner register 时，runner 会在这个目录里生成 config.toml 等配置文件。

2. 可以是空目录，不用提前写内容

首先：

mkdir -p /srv/gitlab-runner/config

然后：

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:alpine

此时：

• 目录是空的

• 没问题，容器启动后还没注册，所以本来也不需要东西。

• 等你执行：

  docker exec -it gitlab-runner gitlab-runner register ...
  

  它会在 /etc/gitlab-runner（也就是宿主机的 /srv/gitlab-runner/config）里写入 config.toml，完成持久化。

3. 如果不手动创建会怎么样？

• 大多数情况下，Docker 会自动在宿主机上创建这个目录。
• 但出于“可预期”和“权限可控”，建议你自己提前 mkdir -p 一下，避免将来你排错时怀疑路径问题。

4. 另一个 -v

-v /var/run/docker.sock:/var/run/docker.sock

这个必须是宿主机上已经存在的 Docker 套接字文件，不能是空的，这个是：

让 Runner 容器能控制宿主机 Docker，去起 job 容器用的。

只要保证：

mkdir -p /srv/gitlab-runner/config
docker run ...（这条）
docker exec -it gitlab-runner gitlab-runner register ...