Issue with Private Git Submodules Not Initializing in Netlify Build

Support
,
1

Hi Team,

I’m encountering an issue where my Netlify build fails to initialize private Git submodules, even though I’ve followed all the steps outlined in your documentation - Repository permissions and linking | Netlify Docs.

Issue Description:

  • My main repository has private Git submodules using SSH URLs (e.g., git@github.com:owner/private-repo.git).

  • I followed Netlify’s deploy key setup:

    • Generated a Deploy Key from Netlify.
    • Added the public key to the private submodule repositories in GitHub → Settings → Deploy Keys with read access.

  • However, during the build process, Netlify fails to initialize the submodules with the following error:

Failed during stage 'preparing repo': Error checking out submodules: 
fatal: Could not read from remote repository.
Please make sure you have the correct access rights and the repository exists.

Troubleshooting Steps Taken:

  1. Verified Deploy Key Access
  • The Netlify-generated key is correctly added as a deploy key to the private submodules.
  • Running ssh -T git@github.com locally confirms that the key should work.
  1. Followed Netlify’s Documentation
  • The private repositories are linked using SSH URLs, per the Netlify docs.
  • I also ensured that submodules are not nested (recursive), as Netlify doesn’t support recursive submodules.
  1. Tried GIT_SUBMODULE_STRATEGY=none
  • Set GIT_SUBMODULE_STRATEGY=none in Netlify’s Environment Variables, but this didn’t prevent Netlify from attempting to initialize submodules before environment variables are picked up.
  1. Attempted to Skip Submodules Manually

Modified the Build Command to but the failure occurs before the build command executes.
rm -rf .git/modules/* frontend/ee server/ee && npm run build

  1. Tried Using HTTPS Instead of SSH
  • Edited .gitmodules to use https://github.com/owner/private-repo.git instead of SSH.
  • This didn’t work because the build server still tries to use SSH authentication.

Questions:

  • Is there a way to ensure that the deploy key is correctly used for submodule authentication?
  • Are there any additional debugging steps we can take to check if Netlify’s build environment is properly using the deploy key?
2

Additional Context:

Our main repository includes two private submodules, but since both belong to the same GitHub organization, GitHub only allows a deploy key to be used in one repository at a time. This creates an issue where Netlify’s deploy key can be added to only one submodule, preventing access to the second one during the build process.

Additionally, Netlify only allows a single SSH key to be generated at a time, and generating a new key overrides the previous one. This means we cannot create separate deploy keys for each submodule.

Is there an alternative way to authenticate both submodules within Netlify’s build environment?

3

Hi, @adishtooljet. One solution is to add the SSH key to a user which has access to both repos. Have you tried that and, if so, what were the results?

4

Hi @luke,

Due to the above constraints. I handle the issue using GitHub Actions, and it’s working as expected.

1 Like