From d93b2526d605e0d67d48d4deabb63c6fb1350ebb Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 15 Jan 2020 17:04:18 -0500 Subject: [PATCH 1/5] Guide: private git submodules using GitHub --- docs/guides/index.rst | 11 ++++++ docs/guides/private-submodules.rst | 58 ++++++++++++++++++++++++++++++ 2 files changed, 69 insertions(+) create mode 100644 docs/guides/private-submodules.rst diff --git a/docs/guides/index.rst b/docs/guides/index.rst index a541cf01bb6..3f1910672ea 100644 --- a/docs/guides/index.rst +++ b/docs/guides/index.rst @@ -46,3 +46,14 @@ These guides will help you customize or tune aspects of the Read the Docs build sitemaps specifying-dependencies wipe-environment + + +Read the Docs for Business how-to guides +---------------------------------------- + +These guides are specific to :doc:`/commercial/index`. + +.. toctree:: + :maxdepth: 1 + + private-submodules diff --git a/docs/guides/private-submodules.rst b/docs/guides/private-submodules.rst new file mode 100644 index 00000000000..bab139cc907 --- /dev/null +++ b/docs/guides/private-submodules.rst @@ -0,0 +1,58 @@ +Using Private Git Submodules with Read the Docs for Business +============================================================ + +Read the Docs uses SSH keys (with read only permissions) in order to clone private repositories. +An SSH key is automatically generated and setup for your main repository, but not for your submodules. +You'll need to use that SSH key in all the repositories of your submodules. + +.. note:: + + You can manage which submodules Read the Docs should clone using a configuration file. + See :ref:`config-file/v2:submodules`. + +GitHub +------ + +For GitHub, Read the Docs uses `deploy keys with read only access `__. +For security reasons, GitHub doesn't allow you to reuse the same SSH key across different repositories. +But you can use `machine users `__ +to give read access to several repositories using only one SSH key. + +- Remove the SSH deploy key that was added to the main repository on GitHub + + - Go to the settings tab of project on GitHub + - Click on :guilabel:`Deploy Keys` + - Delete the key added by ``Read the Docs Commercial (readthedocs.com)`` + +- Create a GitHub user and give it read only permissions to all the necessary repositories. + You can do this by adding the account + as a `collaborator `__, + as an `outside collaborator `__, + or to a `team in an organization `__. +- Get the public SSH key from your Read the Docs project + + - Go to the :guilabel:`Admin` tab of your project + - Click on ``SSH Keys`` + - Click on the fingerprint of the SSH key (it looks like ``6d:ca:6d:ca:6d:ca:6d:ca``) + - Copy the content of the public SSH key + +- Attach the public SSH key to the GitHub user you just created + + - Go to the user's settings + - Click :guilabel:`SSH and GPG keys` + - Click :guilabel:`New SSH key` + - Put a descriptive title and paste the public SSH key from the previous step + - Click :guilabel:`Add SSH key` + +Refer to the `GitHub documentation `__ for more information about machine users. + +GitLab +------ + +Bitbucket +--------- + +Others +------ + +If you are not using any of the above integrations. From 5ec3b76a791d35e96943aaebcd76723c102dee2a Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 15 Jan 2020 18:12:24 -0500 Subject: [PATCH 2/5] Add steps for GitLab --- docs/guides/private-submodules.rst | 48 ++++++++++++++++++++---------- 1 file changed, 33 insertions(+), 15 deletions(-) diff --git a/docs/guides/private-submodules.rst b/docs/guides/private-submodules.rst index bab139cc907..51214b45eef 100644 --- a/docs/guides/private-submodules.rst +++ b/docs/guides/private-submodules.rst @@ -3,24 +3,37 @@ Using Private Git Submodules with Read the Docs for Business Read the Docs uses SSH keys (with read only permissions) in order to clone private repositories. An SSH key is automatically generated and setup for your main repository, but not for your submodules. -You'll need to use that SSH key in all the repositories of your submodules. +You'll need to setup that SSH key on each repository of your submodules. .. note:: You can manage which submodules Read the Docs should clone using a configuration file. See :ref:`config-file/v2:submodules`. +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 ``SSH Keys`` +- Click on the fingerprint of the SSH key (it looks like ``6d:ca:6d:ca:6d:ca:6d:ca``). + +.. note:: + + The private part of the SSH key is kept secret. + GitHub ------ For GitHub, Read the Docs uses `deploy keys with read only access `__. -For security reasons, GitHub doesn't allow you to reuse the same SSH key across different repositories. +GitHub doesn't allow you to reuse a deploy key across different repositories. But you can use `machine users `__ to give read access to several repositories using only one SSH key. - Remove the SSH deploy key that was added to the main repository on GitHub - - Go to the settings tab of project on GitHub + - Go to the project's settings on GitHub - Click on :guilabel:`Deploy Keys` - Delete the key added by ``Read the Docs Commercial (readthedocs.com)`` @@ -29,26 +42,31 @@ to give read access to several repositories using only one SSH key. as a `collaborator `__, as an `outside collaborator `__, or to a `team in an organization `__. -- Get the public SSH key from your Read the Docs project - - - Go to the :guilabel:`Admin` tab of your project - - Click on ``SSH Keys`` - - Click on the fingerprint of the SSH key (it looks like ``6d:ca:6d:ca:6d:ca:6d:ca``) - - Copy the content of the public SSH key - -- Attach the public SSH key to the GitHub user you just created +- Attach the public SSH key from your project on Read the Docs to the GitHub user you just created - Go to the user's settings - - Click :guilabel:`SSH and GPG keys` - - Click :guilabel:`New SSH key` - - Put a descriptive title and paste the public SSH key from the previous step - - Click :guilabel:`Add 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 ` + - Click on :guilabel:`Add SSH key` Refer to the `GitHub documentation `__ for more information about machine users. GitLab ------ +For GitLab, Read the Docs uses `deploy keys with read only access `__. +GitLab allows you to reuse a deploy 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's settings on GitLab +- Click on :guilabel:`Repository` +- Expand the ``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 --------- From c159497eda9eac2ed758cd2c115d9ce3c5b9e719 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 15 Jan 2020 18:35:04 -0500 Subject: [PATCH 3/5] Add guide for bitbucket and others --- docs/guides/private-submodules.rst | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/docs/guides/private-submodules.rst b/docs/guides/private-submodules.rst index 51214b45eef..932726f693a 100644 --- a/docs/guides/private-submodules.rst +++ b/docs/guides/private-submodules.rst @@ -2,8 +2,8 @@ Using Private Git Submodules with Read the Docs for Business ============================================================ Read the Docs uses SSH keys (with read only permissions) in order to clone private repositories. -An SSH key is automatically generated and setup for your main repository, but not for your submodules. -You'll need to setup that SSH key on each repository of your submodules. +An SSH key is automatically generated and added to your main repository, but not on your submodules. +In order to give Read the Docs access to clone your submodules you'll need to add the public SSH key to each repository of your submodules. .. note:: @@ -57,7 +57,7 @@ GitLab For GitLab, Read the Docs uses `deploy keys with read only access `__. GitLab allows you to reuse a deploy key across different repositories. -Since Read the Docs already set the public SSH key on your main repository, +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's settings on GitLab @@ -70,7 +70,23 @@ you only need to add it to each repository of your submodules. Bitbucket --------- +For Bitbucket, Read the Docs uses `access keys with read only access `__. +Bitbucket allows you to reuse an access 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's settings on Bitbucket +- 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. + Others ------ -If you are not using any of the above integrations. +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. From d69b9883907c897ec8616cb848f567512a41b52d Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 18 Feb 2020 11:06:30 -0500 Subject: [PATCH 4/5] Improvements --- docs/guides/private-submodules.rst | 100 ++++++++++++++++------------- 1 file changed, 57 insertions(+), 43 deletions(-) diff --git a/docs/guides/private-submodules.rst b/docs/guides/private-submodules.rst index 932726f693a..282f87fc7a3 100644 --- a/docs/guides/private-submodules.rst +++ b/docs/guides/private-submodules.rst @@ -1,8 +1,12 @@ -Using Private Git Submodules with Read the Docs for Business -============================================================ +Using Private Git Submodules +============================ + +.. warning:: + + This guide is for :doc:`/commercial/index`. Read the Docs uses SSH keys (with read only permissions) in order to clone private repositories. -An SSH key is automatically generated and added to your main repository, but not on your submodules. +A SSH key is automatically generated and added to your main repository, but not to your submodules. In order to give Read the Docs access to clone your submodules you'll need to add the public SSH key to each repository of your submodules. .. note:: @@ -10,83 +14,93 @@ In order to give Read the Docs access to clone your submodules you'll need to ad You can manage which submodules Read the Docs should clone using a configuration file. See :ref:`config-file/v2:submodules`. -Project's SSH Key ------------------ +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 ``SSH Keys`` -- Click on the fingerprint of the SSH key (it looks like ``6d:ca:6d:ca:6d:ca:6d:ca``). +- 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 `__. -GitHub doesn't allow you to reuse a deploy key across different repositories. -But you can use `machine users `__ +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. -- Remove the SSH deploy key that was added to the main repository on GitHub +#. Remove the SSH deploy key that was added to the main repository on GitHub + + - Go to your project on GitHub + - Click on :guilabel:`Settings` + - Click on :guilabel:`Deploy Keys` + - Delete the key added by ``Read the Docs Commercial (readthedocs.com)`` - - Go to the project's settings on GitHub - - Click on :guilabel:`Deploy Keys` - - Delete the key added by ``Read the Docs Commercial (readthedocs.com)`` +#. Create a GitHub user and give it read only permissions to all the necessary repositories. + You can do this by adding the account as: -- Create a GitHub user and give it read only permissions to all the necessary repositories. - You can do this by adding the account - as a `collaborator `__, - as an `outside collaborator `__, - or to a `team in an organization `__. -- Attach the public SSH key from your project on Read the Docs to the GitHub user you just created + - A `collaborator `__ + - An `outside collaborator `__ + - Or a `team in an organization `__ - - Go to the user's settings - - 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 ` - - Click on :guilabel:`Add SSH key` +#. Attach the public SSH key from your project on Read the Docs to the GitHub user you just created -Refer to the `GitHub documentation `__ for more information about machine users. + - Go to the user's settings + - 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 ` + - Click on :guilabel:`Add SSH key` GitLab ------- +~~~~~~ -For GitLab, Read the Docs uses `deploy keys with read only access `__. -GitLab allows you to reuse a deploy key across different repositories. +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's settings on GitLab +- Go to the project of your submodule on GitLab +- Click on :guilabel:`Settings` - Click on :guilabel:`Repository` -- Expand the ``Deploy Keys`` section -- Put a descriptive title and paste the :ref:`public SSH key from your Read the Docs project ` +- 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. +- Repeat the previous steps for each submodule Bitbucket ---------- +~~~~~~~~~ -For Bitbucket, Read the Docs uses `access keys with read only access `__. -Bitbucket allows you to reuse an access key across different repositories. +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's settings on Bitbucket +- 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 ` +- 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. +- Repeat the previous steps for each submodule 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 ` +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. +Refer to your provider's documentation for the steps required to do this. From c0de4a81e2c33ed21d169a77a300da80ee899de1 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Thu, 20 Feb 2020 10:14:57 -0500 Subject: [PATCH 5/5] Improvements - Use numbered items - Add TOC --- docs/guides/private-submodules.rst | 69 ++++++++++++++++-------------- 1 file changed, 38 insertions(+), 31 deletions(-) diff --git a/docs/guides/private-submodules.rst b/docs/guides/private-submodules.rst index 282f87fc7a3..36b97afc676 100644 --- a/docs/guides/private-submodules.rst +++ b/docs/guides/private-submodules.rst @@ -14,15 +14,22 @@ In order to give Read the Docs access to clone your submodules you'll need to ad You can manage which submodules Read the Docs should clone using a configuration file. See :ref:`config-file/v2:submodules`. + +.. contents:: Table of contents + :local: + :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 +#. 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:: @@ -41,26 +48,26 @@ to give read access to several repositories using only one SSH key. #. Remove the SSH deploy key that was added to the main repository on GitHub - - Go to your project on GitHub - - Click on :guilabel:`Settings` - - Click on :guilabel:`Deploy Keys` - - Delete the key added by ``Read the Docs Commercial (readthedocs.com)`` + #. Go to your project on GitHub + #. Click on :guilabel:`Settings` + #. Click on :guilabel:`Deploy Keys` + #. Delete the key added by ``Read the Docs Commercial (readthedocs.com)`` #. Create a GitHub user and give it read only permissions to all the necessary repositories. You can do this by adding the account as: - A `collaborator `__ - An `outside collaborator `__ - - Or a `team in an organization `__ + - A `team in an organization `__ #. Attach the public SSH key from your project on Read the Docs to the GitHub user you just created - - Go to the user's settings - - 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 ` - - Click on :guilabel:`Add SSH key` + #. Go to the user's settings + #. 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 ` + #. Click on :guilabel:`Add SSH key` GitLab ~~~~~~ @@ -70,14 +77,14 @@ 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 +#. 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 ~~~~~~~~~ @@ -87,14 +94,14 @@ 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 +#. 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 Others ~~~~~~