gitlab runner 必须单独安装并注册到 gitlab 实例，未注册则无法接收作业；ubuntu/debian 上应通过官方仓库安装：先执行 curl 命令添加源，再 apt install gitlab-runner，注册时需确保 --url 为实例根地址、--registration-token 为项目级有效令牌。
GitLab Runner 必须单独安装并注册到 GitLab 实例，不能靠 GitLab 服务自带；不注册就收不到任何 job，装了也白装。
Ubuntu/Debian 上安装 gitlab-runner 的正确命令链
用官方仓库安装最稳妥，避免版本错配或缺失依赖：
- 先加签名密钥和源：
curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash - 再装二进制：
sudo apt-get install gitlab-runner - 验证是否可用：
gitlab-runner --version（注意不是gitlab-ci-multi-runner，后者已弃用）
如果执行报 command not found，大概率是 shell PATH 没刷新，重启终端或运行 source /etc/profile。
注册时 URL 和 token 填错是最常见失败原因
注册命令本身不报错，但后续 pipeline 一直 pending，90% 是这里填错了：
-
--url必须填 GitLab 实例根地址，比如https://gitlab.com/或https://your-gitlab.example.com/，不是项目地址，也不是 API 地址 -
--registration-token必须从项目 Settings → CI/CD → Runners 页面里点 New project runner 后复制的 token，不是 group 或 instance 级别的 token - 若遇到
x509: certificate signed by unknown authority，说明 Runner 认不出你的 GitLab 证书，临时跳过验证可加--tls-ca-file=""，但生产环境应把 CA 证书放至/etc/gitlab-runner/certs/your-gitlab.example.com.crt
shell 执行器 vs docker 执行器：选哪个、怎么切
初学者直接用 shell 最快上手，但存在环境残留和权限风险；docker 更干净，但需要宿主机装好 Docker 并把 gitlab-runner 用户加进 docker 组：
- 注册时指定：
--executor shell或--executor docker - 用
shell时，job 在 runner 宿主机的gitlab-runner用户下执行，~/.bashrc不自动加载，PATH 可能不包含/usr/local/bin - 用
docker时，必须在.gitlab-ci.yml中显式写image: node:18，否则默认用alpine:latest，里面没有npm或git - 切换执行器需重注册：先
sudo gitlab-runner unregister --name "my-runner"，再重新register
runner 启动后没反应？检查这三件事
注册完不代表 runner 就在干活，它得作为服务运行起来：
- 确认服务状态：
sudo systemctl status gitlab-runner，如果不是 active (running)，就执行sudo systemctl start gitlab-runner - 检查 runner 是否被禁用：
sudo gitlab-runner list输出里某 runner 后面带DISABLED，说明它被手动停用了，运行sudo gitlab-runner verify --delete清理无效状态，再sudo gitlab-runner start - 查看日志定位卡点：
sudo journalctl -u gitlab-runner -f，重点关注Starting runner后有没有Listening for new jobs—— 没这句，说明根本没连上 GitLab
真正难调的不是安装，而是 runner 和 GitLab 之间那条“看不见的连接”：token 过期、URL 多了个斜杠、防火墙挡了 443、DNS 解析失败……这些都不会在 register 步骤报错，全堆在 job pending 里等你翻日志。
