GitLab Runner需单独安装注册，确认架构（uname -m）后下载对应二进制包，chmod +x赋权；executor依环境选shell（已预装工具链）或docker（需宿主机启用Docker并配置privileged）；注册时指定专用用户及working-directory，确保runner状态online且标签匹配、.gitlab-ci.yml提交至默认分支。

gitlab-runner 不是 GitLab 自带组件，必须单独安装并注册才能执行 CI 任务。装错版本、执行器选错、权限配置不当，CI 作业会直接卡在“pending”或报 permission denied、command not found。

怎么确认系统架构再下载正确二进制包

Linux 上误用 amd64 包跑在 arm64 机器上，或者反过来，gitlab-runner 启动就失败，日志里只显示 cannot execute binary file。

• 先运行 uname -m：输出 x86_64 对应 linux-amd64，aarch64 或 armv8 对应 linux-arm64
• 别信“教程里写的 curl 地址”，2026 年官方已弃用 gitlab-ci-multi-runner 名称，所有新安装必须用 gitlab-runner
• 推荐从 https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/ 手动找对应架构的包，比如：gitlab-runner-linux-arm64
• 下载后务必 chmod +x /usr/local/bin/gitlab-runner，否则 gitlab-runner register 会提示 command not found

注册时 executor 选 shell 还是 docker？关键看你的项目依赖

选错 executor 是最常导致 script 报错的原因。不是“docker 更先进”，而是“环境是否预装”。

Convert Github Repository

适用于以下场景：（1）用户提供 GitHub 仓库 URL 或本地仓库路径，并请求将其转换为其他格式；（2）用户请求导出 GitHub 仓库……

下载

• 如果你的构建脚本里有 npm install、python3 -m venv、make，且服务器上已装好 Node.js/Python/Make 工具链 → 直接选 shell
• 如果项目要求隔离环境（比如 Python 3.9 和 3.11 混用）、或要复用 Docker 镜像（如 node:18-alpine）→ 必须选 docker，且宿主机得提前 systemctl enable --now docker
• 选 docker 后不配 privileged = true，遇到 docker: command not found 或 Cannot connect to the Docker daemon 就是权限没放开
• ssh 和 kubernetes 执行器在普通单机场景基本不用，配置复杂度高，容易因网络或证书中断

注册后服务起不来？检查 user 和 working-directory 权限

gitlab-runner install 命令里的用户不是可有可无的参数，它决定了后续所有 job 的执行上下文。

• 别用 root 装 service：虽然能跑通，但 job 中 sudo 行为不可控，且 .gitlab-ci.yml 里 cache 或 artifacts 路径会因权限被拒绝写入
• 标准做法是创建专用用户：useradd --comment "GitLab Runner" --create-home --shell /bin/bash gitlab-runner
• --working-directory 必须设为该用户的 home 目录（如 /home/gitlab-runner），否则 gitlab-runner start 成功，但 job 日志里反复出现 chdir: no such file or directory
• 启动后手动执行 sudo -u gitlab-runner /usr/local/bin/gitlab-runner run --debug，能立刻暴露权限或路径问题

为什么 .gitlab-ci.yml 里写了 stages 却看不到 pipeline？

注册完 runner 只是“硬件就位”，真正触发 pipeline 还差两个硬性条件，缺一不可。

• 项目 Settings > CI/CD > Runners 页面里，该 runner 状态必须是 online，且勾选了 Run untagged jobs（如果 .gitlab-ci.yml 没写 tags）或标签完全匹配（如 tags: [linux, node] 对应 runner 注册时填的 linux,node）
• .gitlab-ci.yml 文件必须提交到默认分支（通常是 main 或 master），且不能有语法错误——用 gitlab-runner verify 可本地校验，比等 UI 报错快得多
• runner 注册时若勾选了 Lock to current project，那它只会响应这个项目；想复用，注册时选 false，再在项目侧手动启用该 runner
• CI 作业默认超时是 1 小时，如果某 step 卡住（比如 apt update 源慢），会静默失败，建议在 .gitlab-ci.yml 顶层加 timeout: 15 minutes 显式控制

注册和启动只是起点，真正难的是让每个 job 在一致、干净、有权限的环境中稳定执行。很多问题不在配置本身，而在 runner 用户能否读取 /etc 下的证书、能否写入 /tmp、能否访问私有 npm registry 的凭据——这些细节不会报错，只会让 job 随机失败。