importing-private-repositories.rst

How to import private repositories

You can grant access to private Git repositories using . Here is how you set it up.

✅️ Logged in with ?

If you signed up or logged in to Read the Docs with your credentials, all you have to do is to use the normal project import </intro/import-guide>. 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 .

That is the reason why this guide is an extension of the manual Git repository setup </guides/setup/git-repo-manual>, 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:

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.

GitHub

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 <guides/importing-private-repositories:copy your project's public key>
6. Click on Add key

GitLab

For GitLab, you can use deploy keys with read only access.

1. Go to your project on GitLab
2. Click on Settings
3. Click on Repository
4. Expand the Deploy Keys section
5. Put a descriptive title and paste the public SSH key from your Read the Docs project <guides/importing-private-repositories:copy your project's public key>
6. Click on Add key

Bitbucket

For Bitbucket, you can use access keys with read only access.

1. Go your project on Bitbucket
2. Click on Repository Settings
3. Click on Access keys
4. Click on Add key
5. Put a descriptive label and paste the public SSH key from your Read the Docs project <guides/importing-private-repositories:copy your project's public key>
6. Click on Add SSH key

Azure DevOps

For Azure DevOps, you can use SSH key authentication.

1. Go your Azure DevOps page
2. Click on User settings
3. Click on SSH public keys
4. Click on New key
5. Put a descriptive name and paste the public SSH key from your Read the Docs project <guides/importing-private-repositories:copy your project's public key>
6. Click on Add

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 <guides/importing-private-repositories:copy your project's public key> 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 /guides/setup/git-repo-manual.