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.

A cropped screenshot showing the first step of a manual import on |com_brand|.

That is the reason why this guide is an extension of the manual Git repository setup, with the following exception:

  1. Go to https://readthedocs.com/dashboard/import/manual/

  2. In the Repository URL field, you need to provide the SSH version of your repository’s URL. It starts with git@..., for example git@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:

A screenshot of the SSH Keys admin page.
  1. Going to the Admin ‣ SSH Keys tab of your project.

  2. Click on the fingerprint of the SSH key (it looks like 6d:ca:6d:ca:6d:ca:6d:ca)

  3. 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.

  1. Go to your project on GitHub

  2. Click on Settings

  3. Click on Deploy Keys

  4. Click on Add deploy key

  5. Put a descriptive title and paste the public SSH key from your Read the Docs project

  6. Click on Add key

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.