mcpField
G
gitlab-runner-provision

gitlab-runner-provision

github.com/shyxin云与 DevOps537 次安装1 天前更新
代码仓库

关于 gitlab-runner-provision

用于在新 Linux 机器上部署并注册 GitLab Runner 的半自动技能，通过 SSH 执行检测、安装和验证。适合 DevOps 人员按 GitLab 版本配置 Runner，并以 hello-world 流水线验证部署。

主要功能

  1. 01检查并配置 SSH 免密登录
  2. 02远程安装 Docker 并启动 Runner 容器
  3. 03使用令牌注册 Runner 并设置标签
  4. 04验证 Runner 在线状态及 CI 流水线

适用场景

  1. 01为新服务器配置 GitLab CI 执行节点
  2. 02排查 Runner 版本、令牌或标签配置问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/shyxin/skills --skill gitlab-runner-provision

安装后在 Claude Code 中输入/gitlab-runner-provision确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

docs/
architecture.md
scripts/
check_ssh.sh
ensure_ssh.sh
provision.sh
register_runner.sh
verify.sh

详细介绍

来自项目 README

GitLab Runner 新机器部署（gitlab-runner-provision）

在一台新 Linux 机器上把 GitLab Runner 从零跑通，最终以「push 一个 hello-world 流水线变绿」作为验收。半自动：脚本负责检测/生成/校验，需要你确认的敏感输入（token、机器地址）会在每一步明确提示。

📖 觉得流程抽象，先看 docs/architecture.md：整体架构、CI 执行链路、部署流程图解。

输入参数（用户提供）

参数示例说明
SSH 目标root@<新机器IP>新机器地址，可带端口 root@<新机器IP>:22
GitLab URLhttps://<你的GitLab地址>/你的 GitLab 实例地址
注册 token<注册token> 或 glrt-...项目级：项目 → Settings → CI/CD → Runners 页复制；群组级：群组 → Settings → CI/CD → Runners 页复制
Runner tagsdocker（可逗号分隔）注册时的 tag，CI job 用 tags: 匹配
GitLab Runner 版本v15.11.1必须匹配 GitLab 版本：CE 15.x 用 v15.11.1，最新版 Runner 不支持旧 GitLab（gitlab/gitlab-runner:latest 需要 GitLab 16+）

通用前置

# 本机要求：Git Bash / Linux 终端，有 ssh 客户端
# 脚本位置
SKILL_DIR=skills/skills/devops/gitlab-runner-provision

工作流

Step 1：SSH 免登录检查（可能已有，直接检测）
bash "$SKILL_DIR/scripts/check_ssh.sh" root@<新机器IP>
  • 输出 SSH 免登录已可用 → 跳到 Step 2
  • 输出 SSH 免登录不可用 → 执行 Step 1b
Step 1b：配置 SSH 免登录（只需一次密码）
bash "$SKILL_DIR/scripts/ensure_ssh.sh" root@<新机器IP>

脚本自动完成：无密钥则生成 ed25519 密钥 → 追加 ~/.ssh/config 条目 → ssh-copy-id 推送公钥（这一步会要求输入目标机器密码一次）。完成后重新执行 Step 1 验证。

Step 2：安装 Docker + 启动 gitlab-runner 容器
bash "$SKILL_DIR/scripts/provision.sh" root@<新机器IP> v15.11.1

脚本远程检测：

  • Docker 未装 → 自动 curl -fsSL https://get.docker.com | sh 安装
  • gitlab-runner 容器不存在 → 创建并 --restart always 启动

注意：脚本挂载 /var/run/docker.sock 到 runner 容器（docker executor 需要）。若服务器 docker 守护进程 socket 路径不同，手动调整 provision.sh 里的 -v 参数。

Step 3：注册 Runner
bash "$SKILL_DIR/scripts/register_runner.sh" \
  root@<新机器IP> \
  "https://<你的GitLab地址>/" \
  "<注册token>" \
  "runner-on-<host>" \
  "docker"
  • 项目级 token：只服务该项目
  • 群组级 token：服务该群组下所有项目
  • --run-untagged=true：允许 CI job 不带 tags: 也能跑（无需给现有 .gitlab-ci.yml 加 tags）
Step 4：校验
bash "$SKILL_DIR/scripts/verify.sh" root@<新机器IP>

同时到 GitLab 对应项目/群组的 Settings → CI/CD → Runners 确认新 runner 显示 online。

Step 5：最小 CI/CD 验收（hello world）
  1. 在目标 GitLab 项目创建/找到仓库，本地 clone（或已在本地）。
  2. 在仓库根目录添加 .gitlab-ci.yml：
stages:
  - test

hello:
  stage: test
  script:
    - echo "Hello, CI works!"
  1. push 触发流水线：
git add .gitlab-ci.yml
git commit -m "ci: hello world"
git push origin master
  1. 到 GitLab 项目 → CI/CD → Pipelines 看流水线变绿（runner 在线才会开始跑）。

常见问题

现象原因处理
流水线一直 pending无可用 runner，或 runner tags 不匹配确认 runner online；run-untagged=true 可免 tags
register 报 401/403token 无效或权限不足项目级需 Maintainer+，群组级需 Owner（GitLab < 15.7）
容器起不来 Cannot connect to the Docker daemondocker.sock 未挂载或权限检查 provision.sh 的 -v /var/run/docker.sock 与 docker 组权限
Runner 版本太新启动失败GitLab 版本太老不兼容按 GitLab 版本选 gitlab/gitlab-runner:v15.x
job 报 docker: not founddocker executor 的 image 问题确认 runner 容器能访问 Docker Hub/镜像源

设计说明

  • 半自动：安装动作发生在远程服务器，脚本只做"检测 / 生成配置 / 远程执行 / 校验"，token、密码等敏感输入由用户提供，不在仓库或脚本中硬编码。
  • 通用化：不绑定任何具体机器/IP/项目；所有机器信息通过参数传入。

评论

支持 Markdown