GitHub Actions拉取子模块失败问题求助

问题背景 #

私有组织仓库my_private_repo包含组织外的公共仓库my_public_repo作为子模块，本地执行git submodule status正常，但GitHub Actions使用actions/checkout@v3拉取时出现以下错误：

No url found for submodule path 'path_to_my_public_repo' in .gitmodules
The process '/usr/bin/git' failed with exit code 128

可行解决思路 #

1. 校验.gitmodules文件的格式与路径一致性 #

• 确保.gitmodules中path字段的值与子模块在仓库中的实际路径完全匹配，注意GitHub Actions runner默认使用Linux环境，大小写敏感，路径大小写必须严格一致
• 检查文件内是否存在多余空格、缩进错误或特殊字符，比如url行的缩进需与path行保持一致，避免格式解析失败
• 本地执行以下命令验证路径与URL的对应关系，确保输出无异常：

  git config --file .gitmodules --get-regexp path
  git config --file .gitmodules --get-regexp url
  

2. 优化actions/checkout的子模块配置 #

• 明确启用子模块拉取，并设置fetch-depth: 0（默认拉取深度为1，可能无法获取子模块完整历史导致解析失败），示例配置：

  - name: Checkout code
    uses: actions/checkout@v3
    with:
      submodules: true
      fetch-depth: 0
      token: ${{ secrets.GITHUB_TOKEN }}
  

• 若子模块使用git://协议出现网络或权限问题，将.gitmodules中的url替换为https://协议，比如：

  [submodule "path_to_my_public_repo"]
      path = path_to_my_public_repo       
      url = https://github.com/username/my_public_repo.git
  

3. 手动执行子模块同步与更新流程 #

• 跳过checkout动作的默认子模块处理，手动执行同步和初始化步骤，避免自动处理的潜在问题：

  - name: Checkout code
    uses: actions/checkout@v3
    with:
      fetch-depth: 0
  - name: Sync and initialize submodules
    run: |
      git submodule sync --recursive
      git submodule update --init --recursive --force
  

4. 检查runner环境的git配置 #

• 在工作流中添加步骤查看git的子模块相关配置，排查是否存在全局配置干扰：

  git config --list | grep submodule
  

• 确保submodule.recurse等全局配置未覆盖本地.gitmodules的设置，必要时可以在步骤中临时重置相关配置：

  git config --unset-all submodule.recurse
  

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