升级GitLab Runner至17.7.0后CI/CD作业失败，如何解决？

应急手动修复 #

报错核心是Git仓库残留锁文件，导致拉取代码时无法获取锁。根据错误路径/builds/test/example-project/.git/refs/remotes/origin/master.lock，按以下场景清理：

场景1：Runner绑定了主机构建目录 #

如果GitLab Runner配置中通过volumes绑定了主机/builds目录（比如volumes = ["/builds:/builds", "/var/run/docker.sock:/var/run/docker.sock"]），直接在Runner所在的Ubuntu机器上执行：

# 精准删除目标锁文件
sudo rm -f /builds/test/example-project/.git/refs/remotes/origin/master.lock

# 批量清理所有Git残留锁文件（彻底解决潜在冲突）
sudo find /builds -path "*/.git/*" -name "*.lock" -type f | xargs rm -f

场景2：Runner使用Docker匿名卷 #

若未绑定主机目录，直接清理Runner相关的Docker匿名卷（会丢失作业缓存，谨慎操作）：

# 清理所有未使用的Docker卷
docker volume prune -f

长效自动防护 #

在项目的.gitlab-ci.yml中添加pre_get_sources_script，该脚本会在Git拉取源码之前执行，自动清理残留锁文件，避免重复报错：

# 全局生效，所有作业都会先清理锁文件
pre_get_sources_script:
  - |
    if [ -d .git ]; then
      # 清理所有Git相关锁文件
      rm -rf .git/*.lock .git/refs/**/*.lock .git/index.lock
    fi

# 或者仅针对出错的构建作业单独配置
build_docker_image:
  stage: build
  pre_get_sources_script:
    - |
      if [ -d .git ]; then
        rm -rf .git/*.lock .git/refs/**/*.lock .git/index.lock
      fi
  script:
    # 你的Docker构建命令
    - docker build -t your-image .
    - docker push your-image

排查根源防止复发 #

1. 检查Runner日志（主机路径/var/log/gitlab-runner/logs或容器日志docker logs gitlab-runner），确认之前的作业是否因超时、内存不足导致Git进程异常退出，残留锁文件。
2. 若开启了Runner并发作业，确保同项目的并发作业不会复用同一工作目录。可在Runner配置中设置limit = 1限制单项目并发数，或开启FF_USE_NEW_RUNNER_INIT特性（GitLab 16.0+支持），让每个作业使用独立工作目录。
3. 升级Docker镜像版本：当前使用的docker:20.10.14较旧，尝试切换到docker:25.0.3等稳定新版本，避免旧版Git的已知bug。

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