Finally Resolved Failed Netlify Deployments: git subtree solution

I had been stuck since November 22, unable to successfully deploy my Hugo app to Netlify.

Finally, the solution was removing my gitmodules, instead using git subtree to add the theme, which allowed Netlify to deploy a private repository without a deploy key.

Here is a snippet of the error message when deploying; all of them look pretty much the same.

:face_with_symbols_over_mouth: Sample error message

11:18:42 PM: Error checking out submodules: Submodule 'themes/theme-repo' ( registered for path 'themes/theme-repo'
Submodule 'themes/another-theme-repo' ( registered for path 'themes/another-theme-repo'
Cloning into '/opt/build/repo/themes/theme-repo'...
Cloning into '/opt/build/repo/themes/another-theme-repo'...
fatal: could not read Username for '': No such device or address
fatal: clone of '' into submodule path '/opt/build/repo/themes/another-theme-repo' failed
Failed to clone 'themes/another-theme-repo'. Retry scheduled

:-1: Status of my project during failures:

  • Submodules were installed properly using git submodule add
  • Failures occurred with url = https:// in .gitmodules
  • Failures occurred with both a public theme repository and a private theme repository
  • Failures occurred even with my Netlify username matching my GitHub username (after having changed it).
  • Failures occurred even after adding a deploy key generated on the Netlify website to the target theme on GitHub.

:+1: Resolution

  • After much Googling, I finally found this blog post: How to Publish a Hugo Site on Netlify With a Private Theme by Mitja Martini, which I will print to PDF for posterity in case this link ever returns 404.
  • I followed this tutorial to create my subtree repository, which is created from
    git clone --bare <original-theme-repo-url>
    git push --mirror <brand-new-repo-url>
  • Within the website directory – the one that actually deploys to Netlify – I have to run something like this, where $REPO_URL is the brand-new-repo-url created for the bare clone / mirror version of the theme repository.
    git subtree add --prefix themes/mythemename --squash $REPO_URL master
  • Finally, I had to delete all submodules fully to finally get a successful deployment. My Hugo website is live on Netlify.

Hope this helps at least one person.

Please comment below if you have any tricks to use theme submodules with Netlify.


Private repos on netlify can be loaded via ssh. Add the following to your deploy script on Netlify that runs before Hugo:

git config --global url."".insteadOf
git config --global url."git://".insteadOf https://

Then build your URL with environmental variables (DO NOT SAVE your password in your repo :wink: something along the lines of this:

1 Like

Add the following to your deploy script on Netlify that runs before Hugo

git config --global url."".insteadOf

Oops, I believe this (quoted) is where I went wrong with the deploy key route.


More references for git subtree