diff --git a/docs/guides/commercial.rst b/docs/guides/commercial.rst index e7415f9d63d..82fc25c8648 100644 --- a/docs/guides/commercial.rst +++ b/docs/guides/commercial.rst @@ -6,5 +6,6 @@ These guides are specific to :doc:`/commercial/index`. .. toctree:: :maxdepth: 1 + importing-private-repositories private-python-packages private-submodules diff --git a/docs/guides/importing-private-repositories.rst b/docs/guides/importing-private-repositories.rst new file mode 100644 index 00000000000..cf1a397c527 --- /dev/null +++ b/docs/guides/importing-private-repositories.rst @@ -0,0 +1,126 @@ +Manually Importing Private Repositories +======================================= + +.. warning:: + + This guide is for :doc:`/commercial/index`. + +If you are using one of our supported integrations (GitHub, GitLab, or Bitbucket), +we recommend :doc:`connecting your account ` and importing the project from +https://readthedocs.com/dashboard/import. +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. + +#. Manually import your project using an SSH URL +#. Allow access to your project using an SSH key +#. Setup a webhook to build your documentation on every commit + +.. contents:: Table of contents + :local: + :backlinks: none + :depth: 3 + +Importing your project +---------------------- + +#. Go to https://readthedocs.com/dashboard/import/manual/ +#. Fill the :guilabel:`Repository URL` field with the SSH form of your repository's URL, + e.g ``git@github.com:readthedocs/readthedocs.org.git`` +#. Fill the other required fields +#. Click :guilabel:`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 the 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: + +#. Going to the :guilabel:`Admin` tab of your project +#. Click on :guilabel:`SSH Keys` +#. 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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +GitHub +'''''' + +For GitHub, you can use +`deploy keys with read only access `__. + +#. 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 ` +#. Click on :guilabel:`Add key` + +GitLab +'''''' + +For GitLab, you can use `deploy keys with read only access `__. + +#. 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 ` +#. Click on :guilabel:`Add key` +#. Repeat the previous steps for each submodule + +Bitbucket +''''''''' + +For Bitbucket, you can use `access keys with read only access `__. + +#. 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 ` +#. Click on :guilabel:`Add SSH key` + +Azure DevOps +'''''''''''' + +For Azure DevOps, you can use `SSH key authentication `__. + +#. 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 ` +#. Click on :guilabel:`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 :ref:`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 :doc:`/webhooks`. +If you are using an unsupported integration, +you may need to setup a custom integration +using our :ref:`generic webhook `. diff --git a/docs/guides/private-submodules.rst b/docs/guides/private-submodules.rst index d3bc274b7c4..dc88f06eb64 100644 --- a/docs/guides/private-submodules.rst +++ b/docs/guides/private-submodules.rst @@ -25,28 +25,9 @@ In order to give Read the Docs access to clone your submodules you'll need to ad :backlinks: none :depth: 2 - -Copy your project's SSH Key ---------------------------- - -You can find the public SSH key of your Read the Docs project by - -#. Going to the :guilabel:`Admin` tab of your project -#. Click on :guilabel:`SSH Keys` -#. 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 SSH key to your submodules ----------------------------------- - GitHub -~~~~~~ +------ -For GitHub, Read the Docs uses `deploy keys with read only access `__. Since GitHub doesn't allow you to reuse a deploy key across different repositories, you'll need to use `machine users `__ to give read access to several repositories using only one SSH key. @@ -71,48 +52,21 @@ to give read access to several repositories using only one SSH key. #. Click on :guilabel:`SSH and GPG keys` #. Click on :guilabel:`New SSH key` #. Put a descriptive title and paste the - #. :ref:`public SSH key from your Read the Docs project ` + :ref:`public SSH key from your Read the Docs project ` #. Click on :guilabel:`Add SSH key` -GitLab -~~~~~~ +Azure DevOps +------------ -For GitLab, Read the Docs uses `deploy keys with read only access `__, -which allows you to reuse a SSH key across different repositories. -Since Read the Docs already added the public SSH key on your main repository, -you only need to add it to each repository of your submodules. - -#. Go to the project of your submodule 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 ` -#. Click on :guilabel:`Add key` -#. Repeat the previous steps for each submodule - -Bitbucket -~~~~~~~~~ - -For Bitbucket, Read the Docs uses `access keys with read only access `__, -which allows you to reuse a SSH key across different repositories. -Since Read the Docs already set the public SSH key on your main repository, -you only need to add it to each repository of your submodules. - -#. Go to the project of your submodule on Bitbucket -#. Click on :guilabel:`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 ` -#. Click on :guilabel:`Add key` -#. Repeat the previous steps for each submodule +Azure DevOps doesn't have per-project keys. +If you already :ref:`added the SSH key from the main project `, +you don't need to do anything else. 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 ` -to the main repository and each of its submodules. -Refer to your provider's documentation for the steps required to do this. +GitLab and Bitbucket allow you to reuse the same SSH key across different repositories. +Since Read the Docs already added the public SSH key on your main repository, +you only need to add it to each repository of your submodules. +See :ref:`guides/importing-private-repositories:Add the public key to your project` +for more information for these and other providers.