How to import private repositories
==================================

.. include:: /shared/admonition-rtd-business.rst

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

✅️ Logged in with |git_providers_or|?
  If you signed up or logged in to Read the Docs with your |git_providers_or| credentials,
  *all you have to do* is to use the normal :doc:`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 |git_providers_or|.

.. image:: /img/screenshot-com-manual-import.png
   :scale: 50%
   :align: right
   :alt: 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 :doc:`manual Git repository setup </guides/setup/git-repo-manual>`,
with the following exception:

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

#. In the :guilabel:`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:

.. image:: /img/screenshot-com-ssh-keys.png
   :scale: 50%
   :align: right
   :alt: A screenshot of the SSH Keys admin page.

#. Going to the :menuselection:`Admin --> SSH Keys` 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 :guilabel:`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.

.. tabs::

   .. tab:: GitHub

      For GitHub, you can use
      `deploy keys with read only access <https://docs.github.com/en/developers/overview/managing-deploy-keys#deploy-keys>`__.

      #. Go to your project on GitHub
      #. Click on :guilabel:`Settings`
      #. Click on :guilabel:`Deploy Keys`
      #. Click on :guilabel:`Add deploy key`
      #. Put a descriptive title and paste the
         :ref:`public SSH key from your Read the Docs project <guides/importing-private-repositories:copy your project's public key>`
      #. Click on :guilabel:`Add key`

   .. tab:: GitLab

      For GitLab, you can use `deploy keys with read only access <https://docs.gitlab.com/ee/user/project/deploy_keys/index.html>`__.

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

   .. tab:: Bitbucket

      For Bitbucket, you can use `access keys with read only access <https://confluence.atlassian.com/bitbucket/access-keys-294486051.html>`__.

      #. Go your project on Bitbucket
      #. Click on :guilabel:`Repository Settings`
      #. Click on :guilabel:`Access keys`
      #. Click on :guilabel:`Add key`
      #. Put a descriptive label and paste the
         :ref:`public SSH key from your Read the Docs project <guides/importing-private-repositories:copy your project's public key>`
      #. Click on :guilabel:`Add SSH key`

   .. tab:: Azure DevOps

      For Azure DevOps, you can use `SSH key authentication <https://docs.microsoft.com/en-us/azure/devops/repos/git/use-ssh-keys-to-authenticate?view=azure-devops>`__.

      #. Go your Azure DevOps page
      #. Click on :guilabel:`User settings`
      #. Click on :guilabel:`SSH public keys`
      #. Click on :guilabel:`New key`
      #. Put a descriptive name and paste the
         :ref:`public SSH key from your Read the Docs project <guides/importing-private-repositories:copy your project's public key>`
      #. Click on :guilabel:`Add`

   .. tab:: 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 :ref:`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 :doc:`/guides/setup/git-repo-manual`.