需先安装并注册GitLab Runner才能触发Pipeline；通过Homebrew安装、sudo注册为系统服务、可选配置Docker执行器，最后用.gitlab-ci.yml验证Runner是否Active且能成功运行任务。
如果您在Mac系统上需要为GitLab项目启用CI/CD能力，但尚未安装并注册Runner，则无法触发任何Pipeline任务。以下是针对macOS平台完成GitLab Runner安装、注册与基础CI配置的完整操作路径：
一、使用Homebrew安装GitLab Runner
Homebrew是macOS最主流的包管理工具，通过它可快速部署稳定版本的GitLab Runner二进制程序，避免手动下载与权限配置风险。
1、打开终端，执行命令安装Homebrew（若尚未安装）：
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
2、更新Homebrew源并升级已有软件：
brew update && brew upgrade
3、执行安装命令：
brew install gitlab-runner
4、验证安装是否成功：
gitlab-runner --version
输出应显示类似GitLab Runner v17.9.0 (a1b2c3d4)的版本信息，表示安装完成。
二、以系统服务方式注册并启动Runner
将Runner注册为macOS系统级服务，可确保其随系统启动自动运行，并以独立用户身份隔离执行环境，提升安全性与稳定性。
1、执行注册命令：
sudo gitlab-runner register
2、按提示依次输入以下信息：
– GitLab实例URL（如https://gitlab.com或自建实例地址）
– 项目注册Token（在GitLab项目Settings > CI/CD > Runners页面获取，务必复制未过期的token）
– Runner描述（如macos-dev-runner）
– Tag列表（可留空或填入macos,shell）
– 是否锁定到当前项目（建议选true）
– 执行器类型（输入shell）
3、注册成功后，启动Runner服务：
sudo gitlab-runner start
4、确认服务状态：
sudo gitlab-runner status
返回gitlab-runner: Service is running!即表示已就绪。
三、配置专属Runner并启用Docker支持（高级选项）
当项目需构建容器镜像或依赖特定Linux环境时，仅用shell执行器受限；启用Docker执行器可在macOS上运行Linux容器化Job，实现跨平台一致性构建。
1、安装Docker Desktop for Mac并启动应用（确保Docker daemon处于运行状态）
2、重新注册一个Docker类型的Runner：
sudo gitlab-runner register --executor docker
3、输入相同URL与Token后，按提示设置：
– 执行器参数中指定默认镜像（如node:18-alpine）
– 启用特权模式（输入true，用于Docker-in-Docker场景）
– 挂载Docker socket（添加绑定：/var/run/docker.sock:/var/run/docker.sock）
4、编辑Runner配置文件启用并发与资源限制：
sudo nano /usr/local/etc/gitlab-runner/config.toml
5、在对应[[runners]]区块下添加：
concurrent = 2
output_limit = 4096
四、验证Runner可用性与调试配置
注册完成后需立即验证Runner能否被GitLab识别并响应任务，同时排查常见连接与权限问题。
1、前往GitLab项目页面，进入Settings > CI/CD > Runners
2、确认新注册的Runner显示为Active且Online状态
3、在项目根目录创建测试用.gitlab-ci.yml文件：
stages:
- test
test_job:
stage: test
script:
- echo "Hello from macOS GitLab Runner"
4、提交并推送该文件：
git add .gitlab-ci.yml
git commit -m "Add CI test config"
git push origin main
5、进入CI/CD > Pipelines页面，观察Pipeline是否触发并成功完成；若失败，点击作业查看full raw log定位错误源头。
