在 macos 上搭建 gitlab ci 工具链需完成三步：安装注册 gitlab runner（选 shell executor）、编写 .gitlab-ci.yml 定义 build/deploy 阶段并匹配 tags、配置 ssh 免密及目标服务器写入权限，全程无需 jenkins 等额外平台。
在 macos 上搭建面向开发的持续集成工具链，核心是用好 gitlab ci 自身能力，不额外引入 jenkins 等重型平台。整个流程围绕 runner 执行、yaml 编排和部署通道打通三件事展开，本地 mac 既可作 runner 主机，也能作为轻量级 ci 构建节点。
安装并注册 GitLab Runner
Runner 是实际干活的执行器，必须先装好并绑定到项目：
- 用 Homebrew 安装：brew install gitlab-runner
- 进入 GitLab 项目 → Settings → CI/CD → Runners，复制页面提供的 URL 和 Token
- 终端运行 gitlab-runner register，按提示填写：
- GitLab 实例地址（如 https://gitlab.example.com/）
- Project token（上一步复制的）
- Runner 描述（例如 mac-ci-runner）
- Tags（比如 mac, ci，后续 job 需匹配）
- Executor 选 shell（适合 macOS 本机执行，无需 Docker）
- 注册成功后，回到 GitLab Runners 页面，确认状态为 online，并勾选 “Run untagged jobs” 或确保 job 明确指定 tags
编写 .gitlab-ci.yml 定义流水线
这个文件放在项目根目录，决定每个阶段做什么。典型结构分构建与部署两步：
- stages 声明顺序：build → deploy（测试阶段可按需加入）
-
build 阶段执行依赖安装和打包，例如前端项目：
- script: yarn install && yarn build
- artifacts: 指定 dist/ 目录，供 deploy 阶段使用
- tags: 匹配注册时填的 mac
-
deploy 阶段推送产物到服务器：
- script: 用 scp 上传，如 scp -r ./dist/* user@192.168.1.100:/var/www/app/
- only: 设为 [master]，避免 dev 分支误触发
- 确保该 job 也带 tags: [mac]
配置 SSH 免密与目标权限
Runner 要能无交互登录远程服务器并写入文件，这是自动化落地的关键：
- 在 macOS 上生成密钥（若尚未有）：ssh-keygen -t ed25519 -C "ci@mac"
- 将公钥复制到目标服务器：ssh-copy-id user@192.168.1.100
- 验证是否免密：ssh user@192.168.1.100 ls /var/www/
- 检查目标路径权限，确保 user 对 /var/www/app/ 有写权限（必要时 sudo chown -R user:www-data /var/www/app）
验证与调试技巧
首次运行容易卡在权限或路径问题，建议分步验证：
- 手动在 Mac 终端执行一遍 yarn build 和 scp 命令，确认流程通顺
- GitLab Pipeline 页面点 “Retry” 重跑失败 job，查看完整日志
- 在 script: 中加 set -x 开启命令回显，便于定位哪一行出错
- 避免在 CI 脚本中调用需交互的命令（如 webpack-bundle-analyzer），会阻塞进程
