GitLab流水线报错fatal: Couldn't find remote ref求助

我已经为生产环境的master仓库创建了Runner并配置流水线，但运行时出现报错：fatal: Couldn't find remote ref。我在Linux环境下测试过可以正常克隆仓库，网络连接也没问题，求排查解决思路。

流水线配置代码 #

image: maven:3.6.2-jdk-8

default:

stages:
    - build_prod
    - deploy_prod
    - run_prod


variables:
  GIT_SUBMODULE_STRATEGY: recursive
  MAVEN_CLI_OPTS: "--batch-mode"
  GITLAB_BASE_URL: "https://gitlab.com"


build_prod:
  stage: build
  before_script:
    - git submodule update --remote
  only:
     variables:
      - $CI_COMMIT_REF_NAME
  tags:
      - prod    
  script:
    - mvn $MAVEN_CLI_OPTS package -f build.pom.xml -P prod
  environment:
    name: production
  artifacts:
    paths:
      - target/dev-1.0-SNAPSHOT.war
  when: manual
  only:
  - master

  
deploy_prod:    
    stage: deploy
    only:
      variables:
      - $CI_COMMIT_REF_NAME
    tags:
      - prod
    variables:
      GIT_STRATEGY: none
    script:
      - cp /home/gitlab-runner/builds/UtZuJjHy/0/dev/backend/target/LXRLite-1.0-SNAPSHOT.war /home/gitlab-runner/patch/$CI_COMMIT_REF_NAME/
      - cd /home/gitlab-runner
      - sh key.sh
    environment:
      name: production
    when: manual
    only:
    - master


    
run_prod:
    stage: run
    only:
      variables:
      - $CI_COMMIT_REF_NAME
    tags:
      - prod
    variables:
      GIT_STRATEGY: none
    script:
      - ls
      - cd /home/gitlab-runner
      - sh keycomp.sh $DEPLOY_KEY
    #   - cp /home/gitlab-runner/patch/master/dev-1.0-SNAPSHOT.war /disk2/tomcat/webapps/ROOT.war
    #   - sh tomcat_restart.sh
    environment:
      name: production
    when: manual  
    only:
    - master

1. 定位子模块问题 #

报错大概率出在build_prod阶段的git submodule update --remote命令：

• 检查仓库根目录的.gitmodules文件，确认子模块的远程URL、分支名是否正确，有没有拼写错误
• 验证子模块对应的远程仓库是否存在指定分支，是否被删除或改名
• 在Runner所在机器上，手动进入项目目录执行git submodule update --remote，复现报错以定位具体是哪个子模块出问题

2. 验证Runner的仓库访问权限 #

• 你测试克隆用的账号和Runner使用的账号可能不同，检查Runner的SSH密钥或CI/CD令牌是否有权限访问所有子模块仓库
• 确认Runner机器的Git配置能正常解析子模块的远程地址，排查是否存在代理、DNS解析异常（主仓库能克隆不代表子模块地址也能正常访问）

3. 清理冗余的流水线规则 #

build_prod阶段重复写了两次only规则，其中only: variables: - $CI_COMMIT_REF_NAME属于冗余配置，可能导致分支匹配逻辑冲突，建议删除该规则，只保留only: - master

4. 协调子模块更新策略 #

你同时设置了GIT_SUBMODULE_STRATEGY: recursive（Runner自动更新子模块）和手动执行git submodule update --remote，两者可能冲突：

• 尝试删除before_script里的git submodule update --remote，仅依赖内置的子模块更新策略
• 或者在.gitmodules中明确指定子模块的分支，比如添加branch = master（替换为子模块实际使用的分支名）

5. 检查变量与路径正确性 #

• 在build_prod的script中添加echo $CI_COMMIT_REF_NAME，确认变量是否正确取值为master
• deploy_prod阶段的文件路径是硬编码的，可能因Runner配置或项目ID变化失效，建议改用CI内置变量，比如$CI_PROJECT_DIR/target/LXRLite-1.0-SNAPSHOT.war替代绝对路径

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