如何将私有Git仓库添加为子模块 解决GitHub Actions拉取失败问题

问题根因 #

本地执行git submodule update能正常运行，是因为本地存储了对应私有仓库的访问凭证（SSH密钥或HTTPS令牌），拥有子模块仓库的读取权限。
GitHub Actions运行器默认使用的自动生成GITHUB_TOKEN仅对当前运行工作流的仓库有权限，无其他私有仓库的访问权限；同时Git服务端对无权限访问的私有仓库会统一返回url not found响应（避免泄露私有仓库的存在信息），就会触发你看到的报错。

可用解决方案 #

方案1：配置子模块部署密钥（最小权限原则，推荐） #

• 本地执行ssh-keygen -t ed25519 -C "gh-actions-submodule-access"生成一对SSH密钥，生成时不要设置密码短语
• 打开私有子模块仓库的设置页，进入「Deploy Keys」配置项，把生成的公钥（后缀为.pub的文件内容）添加进去，勾选「允许读取访问」
• 打开主仓库（运行工作流的仓库）的设置页，进入「Secrets and variables-Actions」配置项，新建一个仓库密钥，命名为SUBMODULE_SSH_KEY，值为生成的私钥文件内容
• 修改工作流的Checkout步骤配置，替换为以下内容：

- name: Checkout
  uses: actions/checkout@v3
  with:
    submodules: recursive
    ssh-key: ${{ secrets.SUBMODULE_SSH_KEY }}

配置完成后可以删掉后续单独执行git submodule update的步骤，checkout动作会自动完成所有层级子模块的拉取，不需要重复执行命令。

方案2：使用有权限的个人访问令牌 #

如果所有子模块和主仓库都归属同一个个人账号或组织，可以用个人访问令牌简化配置：

• 生成一个勾选了repo全权限范围的GitHub个人访问令牌（PAT）
• 把这个PAT保存到主仓库的Actions密钥中，命名为REPO_PAT
• 修改Checkout步骤配置：

- name: Checkout
  uses: actions/checkout@v3
  with:
    submodules: recursive
    token: ${{ secrets.REPO_PAT }}

配置注意事项 #

• 检查子模块的仓库地址配置，不要使用本地自定义的SSH别名或本地路径，统一使用官方SSH格式git@github.com:<仓库所属用户名/组织名>/<子模块仓库名>.git
• 不需要在Checkout步骤之后额外叠加git submodule update --init --recursive命令，只要checkout步骤传入了有效凭证，会自动完成子模块初始化和拉取，重复执行反而可能触发权限冲突。

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