How to use private Git submodules
Warning
This guide is for About Read the Docs for Business.
If you are using private Git repositories and they also contain private Git submodules, you need to follow a few special steps.
Read the Docs uses SSH keys (with read only permissions) in order to clone private repositories. A SSH key is automatically generated and added to your main repository, but not to your submodules. In order to give Read the Docs access to clone your submodules you’ll need to add the public SSH key to each repository of your submodules.
Note
You can manage which submodules Read the Docs should clone using a configuration file. See submodules.
Make sure you are using
SSH
URLs for your submodules (git@github.com:readthedocs/readthedocs.org.git
for example) in your.gitmodules
file, nothttp
URLs.
GitHub
Since GitHub doesn’t allow you to reuse a deploy key across different repositories, you’ll need to use machine users to give read access to several repositories using only one SSH key.
Remove the SSH deploy key that was added to the main repository on GitHub
Go to your project on GitHub
Click on Settings
Click on Deploy Keys
Delete the key added by
Read the Docs Commercial (readthedocs.com)
Create a GitHub user and give it read only permissions to all the necessary repositories. You can do this by adding the account as:
Attach the public SSH key from your project on Read the Docs to the GitHub user you just created
Go to the user’s settings
Click on SSH and GPG keys
Click on New SSH key
Put a descriptive title and paste the public SSH key from your Read the Docs project
Click on Add SSH key
Azure DevOps
Azure DevOps does not have per-repository SSH keys, but keys can be added to a user instead. As long as this user has access to your main repository and all its submodules, Read the Docs can clone all the repositories with the same key.
Others
GitLab and Bitbucket allow you to reuse the same SSH key across different repositories. Since Read the Docs already added the public SSH key on your main repository, you only need to add it to each submodule repository.
See also