GitHub Action拉取子模块失败，返回退出码1求助

问题复现 #

使用GitHub Action部署至App Service时，拉取仓库（含子模块）失败，返回Git退出码1，报错日志如下：

Fetching the repository
/usr/bin/git -c protocol.version=2 fetch --no-tags --prune --progress --no-recurse-submodules --depth=1 origin +refs/heads/v2*:refs/remotes/origin/v2* +refs/tags/v2*:refs/tags/v2*
The process '/usr/bin/git' failed with exit code 1
Waiting 16 seconds before trying again
/usr/bin/git -c protocol.version=2 fetch --no-tags --prune --progress --no-recurse-submodules --depth=1 origin +refs/heads/v2*:refs/remotes/origin/v2* +refs/tags/v2*:refs/tags/v2*
The process '/usr/bin/git' failed with exit code 1
Waiting 16 seconds before trying again
/usr/bin/git -c protocol.version=2 fetch --no-tags --prune --progress --no-recurse-submodules --depth=1 origin +refs/heads/v2*:refs/remotes/origin/v2* +refs/tags/v2*:refs/tags/v2*
Error: The process '/usr/bin/git' failed with exit code 1

排查与解决步骤 #

• 开启Checkout Action的子模块拉取
  默认的actions/checkout不会自动拉取子模块，需显式配置参数，同时传入已授权SSO的PAT：

  - name: 拉取代码及子模块
    uses: actions/checkout@v4
    with:
      submodules: 'true'
      token: ${{ secrets.YOUR_PAT_NAME }}
  

• 验证PAT权限与SSO授权
  确认你的PAT已勾选repo权限（覆盖子模块所在仓库的读取权限），且完成了目标组织的SSO授权。若子模块为私有仓库，PAT必须拥有该仓库的访问权限。

• 检查子模块远程地址格式
  查看.gitmodules文件中的子模块地址，若为SSH格式（git@github.com:...），可改为HTTPS格式（https://github.com/...），确保能通过PAT完成认证。修改后执行git submodule sync同步地址，提交修改至仓库。

• 关闭浅克隆避免拉取限制
  日志中使用了--depth=1的浅克隆，可能导致子模块拉取失败。在Checkout Action中配置完整克隆：

  - name: 拉取完整代码及子模块
    uses: actions/checkout@v4
    with:
      submodules: 'true'
      token: ${{ secrets.YOUR_PAT_NAME }}
      fetch-depth: 0
  

• 本地验证拉取流程
  使用相同PAT在本地测试拉取，确认权限和配置是否正常：

  git clone --recurse-submodules https://<你的PAT>@github.com/你的组织/你的仓库.git
  

  若本地失败，优先排查PAT权限或子模块配置；若本地成功，再检查Action环境中的变量或配置是否有误。

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