Manually Importing Private Repositories

Warning

This guide is for users of Read the Docs for Business. If you are using GitHub, GitLab, or Bitbucket, we recommend connecting your account and importing your project from https://readthedocs.com/dashboard/import instead of importing it manually.

If you are using an unsupported integration, or don’t want to connect your account, you’ll need to do some extra steps in order to have your project working.

  1. Manually import your project using an SSH URL

  2. Allow access to your project using an SSH key

  3. Setup a webhook to build your documentation on every commit

Importing your project

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

  2. Fill the Repository URL field with the SSH form of your repository’s URL, e.g git@github.com:readthedocs/readthedocs.org.git

  3. Fill the other required fields

  4. Click Next

Giving access to your project with an SSH key

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

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 public key to your project

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

  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

  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

  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

  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 to your repository. Refer to your provider’s documentation for the steps required to do this.

Webhooks

To build your documentation on every commit, you’ll need to manually add a webhook, see Incoming Webhooks and Automation. If you are using an unsupported integration, you may need to setup a custom integration using our generic webhook.