GitLab CI Shell Runner返回500错误，克隆仓库失败求助

我碰到过好几个用Shell执行器的GitLab Runner出现这种克隆到一半卡住/失败的情况，大部分都是权限或者认证的问题，咱们一步步来排查解决：

1. 先手动模拟Runner的操作，定位具体错误 #

Shell执行器是用gitlab-runner系统用户来执行任务的，咱们切换到这个用户，手动尝试克隆你的项目，看具体报什么错——这是最快定位问题的方法：

# 切换到gitlab-runner用户
sudo su - gitlab-runner
# 替换成你项目的实际仓库地址（HTTPS或SSH都可以）
git clone https://your-gitlab-domain/your-group/your-project.git

如果这一步报错，问题就明确了，跟着错误提示解决就行；如果能成功克隆，再往下看配置相关的问题。

2. 最常见的问题：权限配置错误 #

2.1 Runner工作目录权限 #

检查GitLab Runner默认的工作目录（/home/gitlab-runner/builds）是否对gitlab-runner用户有读写权限：

ls -ld /home/gitlab-runner/builds
# 正常输出应该是类似 drwxr-xr-x 3 gitlab-runner gitlab-runner ...

如果权限不对，修改权限：

sudo chown -R gitlab-runner:gitlab-runner /home/gitlab-runner/builds
sudo chmod -R 755 /home/gitlab-runner/builds

2.2 GitLab仓库目录的访问权限 #

如果你的Runner尝试从本地GitLab仓库克隆（而非通过HTTP/SSH），需要确保gitlab-runner用户对/sites/gitlab/git-data/repositories有读权限：

# 调整仓库目录权限
sudo chmod -R 750 /sites/gitlab/git-data/repositories
# 把gitlab-runner加入git用户组（GitLab仓库目录通常属于git用户）
sudo usermod -aG git gitlab-runner

3. SSH认证问题（如果用SSH克隆） #

如果项目是用SSH地址配置的，gitlab-runner用户需要有能访问项目的SSH密钥：

1. 切换到gitlab-runner用户生成密钥（不要设密码，否则Runner执行时会卡住要输入密码）：

   sudo su - gitlab-runner
   ssh-keygen -t ed25519 -C "gitlab-runner@your-server"
   # 一路回车即可
   

2. 复制公钥内容：

   cat ~/.ssh/id_ed25519.pub
   

3. 登录GitLab，进入你的项目 → Settings → Repository → Deploy keys，粘贴公钥，勾选"Read access allowed"（仅克隆的话读权限足够），保存。
4. 测试SSH连接：

   ssh -T git@your-gitlab-domain.com
   # 出现类似 "Welcome to GitLab, @gitlab-runner!" 就说明认证成功了
   

4. HTTPS克隆的SSL证书问题 #

如果用HTTPS克隆，而你的GitLab用的是自签SSL证书，gitlab-runner用户的Git可能不信任这个证书，导致克隆失败：

• 信任GitLab的自签证书（推荐）：

  sudo su - gitlab-runner
  # 替换成你实际的证书路径，Omnibus安装的GitLab证书通常在/etc/gitlab/ssl/下
  git config --global http.sslCAInfo /etc/gitlab/ssl/your-gitlab-cert.crt
  

• （仅测试用，不推荐生产）临时禁用SSL验证：

  git config --global http.sslVerify false
  

5. 磁盘空间不足 #

最后检查一下克隆目录所在的磁盘有没有满：

df -h /sites/gitlab/git-data
# 看Use%列，如果接近100%，清理磁盘或者扩容即可

按照上面的步骤排查，基本能解决克隆失败的问题。

内容的提问来源于stack exchange，提问作者Yokall