Using Private Git Submodules

Warning

This guide is for Read the Docs for Business.

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.

Note

Make sure you are using SSH URLs for your submodules (git@github.com:readthedocs/readthedocs.org.git for example) in your .gitmodules file, not http URLs.

Copy your project’s SSH Key

You can find the public SSH key of your Read the Docs project by

1. Going to the Admin tab of your project
2. Click on SSH Keys
3. Click on the fingerprint of the SSH key (it looks like 6d:ca:6d:ca:6d:ca:6d:ca)
4. Copy the text from the Public key section

Note

The private part of the SSH key is kept secret.

Add the SSH key to your submodules

GitHub

For GitHub, Read the Docs uses deploy keys with read only access. 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.

1. Remove the SSH deploy key that was added to the main repository on GitHub
   1. Go to your project on GitHub
   2. Click on Settings
   3. Click on Deploy Keys
   4. Delete the key added by Read the Docs Commercial (readthedocs.com)
2. Create a GitHub user and give it read only permissions to all the necessary repositories. You can do this by adding the account as:
   • A collaborator
   • An outside collaborator
   • A team in an organization
3. Attach the public SSH key from your project on Read the Docs to the GitHub user you just created
   1. Go to the user’s settings
   2. Click on SSH and GPG keys
   3. Click on New SSH key
   4. Put a descriptive title and paste the
   5. public SSH key from your Read the Docs project
   6. Click on Add SSH key

GitLab

For GitLab, Read the Docs uses deploy keys with read only access, which allows you to reuse a 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 repository of your submodules.

1. Go to the project of your submodule on GitLab
2. Click on Settings
3. Click on Repository
4. Expand the Deploy Keys section
5. Put a descriptive title and paste the
6. public SSH key from your Read the Docs project
7. Click on Add key
8. Repeat the previous steps for each submodule

Bitbucket

For Bitbucket, Read the Docs uses access keys with read only access, which allows you to reuse a SSH key across different repositories. Since Read the Docs already set the public SSH key on your main repository, you only need to add it to each repository of your submodules.

1. Go to the project of your submodule on Bitbucket
2. Click on Settings
3. Click on Access keys
4. Click on Add key
5. Put a descriptive label and paste the
6. public SSH key from your Read the Docs project
7. Click on Add key
8. Repeat the previous steps for each submodule

Others

If you are not using any of the above providers. Read the Docs will still generate a pair of SSH keys. You’ll need to add the public SSH key from your Read the Docs project to the main repository and each of its submodules. Refer to your provider’s documentation for the steps required to do this.