How to import private repositories
Note
This feature is only available on Read the Docs for Business.
You can grant access to private Git repositories using Read the Docs for Business. Here is how you set it up.
- ✅️ Logged in with GitHub, Bitbucket, or GitLab?
If you signed up or logged in to Read the Docs with your GitHub, Bitbucket, or GitLab credentials, all you have to do is to use the normal project import. Your Read the Docs account is connected to your Git provider and will let you choose from private Git repositories and configure them for you.
You can still use the below guide if you need to recreate SSH keys for a private repository.
- ⬇️ Logging in with another provider or email?
For all other Git provider setups, you will need to configure the Git repository manually.
Follow the steps below.
Importing your project manually
Git repositories aren’t automatically listed for setups that are not connected to GitHub, Bitbucket, or GitLab.
That is the reason why this guide is an extension of the manual Git repository setup, with the following exception:
In the Repository URL field, you need to provide the SSH version of your repository’s URL. It starts with
git@..., for examplegit@github.com:readthedocs/readthedocs.org.git.
After importing your project the build will fail, because Read the Docs doesn’t have access to clone your repository. To give access, you’ll need to add your project’s public SSH key to your VCS provider.
Copy your project’s public key
Next step is to locate a public SSH key which Read the Docs has automatically generated:
Going to the tab of your project.
Click on the fingerprint of the SSH key (it looks like
6d:ca:6d:ca:6d:ca:6d:ca)Copy the text from the Public key section
Note
The private part of the SSH key is kept secret.
Add the public key to your project
Now that you have copied the public key generated by Read the Docs, you need to add it to your Git repository’s settings.
For GitHub, you can use deploy keys with read only access.
Go to your project on GitHub
Click on Settings
Click on Deploy Keys
Click on Add deploy key
Put a descriptive title and paste the public SSH key from your Read the Docs project
Click on Add key
For GitLab, you can use deploy keys with read only access.
Go to your project on GitLab
Click on Settings
Click on Repository
Expand the Deploy Keys section
Put a descriptive title and paste the public SSH key from your Read the Docs project
Click on Add key
For Bitbucket, you can use access keys with read only access.
Go your project on Bitbucket
Click on Repository Settings
Click on Access keys
Click on Add key
Put a descriptive label and paste the public SSH key from your Read the Docs project
Click on Add SSH key
For Azure DevOps, you can use SSH key authentication.
Go your Azure DevOps page
Click on User settings
Click on SSH public keys
Click on New key
Put a descriptive name and paste the public SSH key from your Read the Docs project
Click on Add
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 your repository. Refer to your provider’s documentation for the steps required to do this.
Webhooks
Finally, since this is a manual project import:
Don’t forget to add the Read the Docs webhook!
To automatically trigger new builds on Read the Docs, you’ll need to manually add a webhook, see How to manually configure a Git repository.