diff --git a/docs/user/guides/importing-private-repositories.rst b/docs/user/guides/importing-private-repositories.rst index f5bd09f916f..b4c7a533076 100644 --- a/docs/user/guides/importing-private-repositories.rst +++ b/docs/user/guides/importing-private-repositories.rst @@ -1,39 +1,43 @@ How to import private repositories ================================== -.. warning:: - - This guide is for users of :doc:`/commercial/index`. - **If you are using GitHub, GitLab, or Bitbucket**, - we recommend :doc:`connecting your account ` and importing your project from - https://readthedocs.com/dashboard/import instead of importing it manually. +.. include:: /shared/admonition-rtd-business.rst You can grant access to private Git repositories using |com_brand|. Here is how you set it up. -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**. +✅️ 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 `. + 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 +------------------------------- -#. **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** +Git repositories aren't automatically listed for setups that are not connected to |git_providers_or|. -.. contents:: Table of contents - :local: - :backlinks: none - :depth: 3 +.. 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|. -Importing your project ----------------------- +That is the reason why this guide is an extension of the :doc:`manual Git repository setup `, +with the following exception: #. 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 ---------------------------------------------- +#. 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. @@ -42,10 +46,14 @@ To give access, you'll need to add your project's public SSH key to your VCS pro Copy your project's public key ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can find the public SSH key of your Read the Docs project by: +Next step is to locate a public SSH key which Read the Docs has automatically generated: -#. Going to the :guilabel:`Admin` tab of your project -#. Click on :guilabel:`SSH Keys` +.. 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 @@ -56,73 +64,74 @@ You can find the public SSH key of your Read the Docs project by: Add the public key to your project ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -GitHub -'''''' +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 `__. + 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` + #. 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 -'''''' + .. tab:: GitLab -For GitLab, you can use `deploy keys with read only access `__. + 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` + #. 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` -Bitbucket -''''''''' + .. tab:: Bitbucket -For Bitbucket, you can use `access keys with read only access `__. + 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` + #. 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 -'''''''''''' + .. tab:: Azure DevOps -For Azure DevOps, you can use `SSH key authentication `__. + 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` + #. 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 -'''''' + .. 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 ` -to your repository. -Refer to your provider's documentation for the steps required to do this. + 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:`/integrations`. -If you are using an unsupported integration, -you may need to setup a custom integration -using our :ref:`generic webhook `. +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/git-integrations`. diff --git a/docs/user/guides/private-submodules.rst b/docs/user/guides/private-submodules.rst index ee8990ead03..0bc67d69310 100644 --- a/docs/user/guides/private-submodules.rst +++ b/docs/user/guides/private-submodules.rst @@ -65,7 +65,7 @@ Read the Docs can clone all the repositories with the same key. .. seealso:: - :ref:`Allow access to your Azure DevOps repository with an SSH key `. + :ref:`Allow access to your Azure DevOps repository with an SSH key `. Others ------ @@ -76,4 +76,4 @@ you only need to add it to each submodule repository. .. seealso:: - :ref:`guides/importing-private-repositories:Giving access to your project with an SSH key` + :doc:`/guides/importing-private-repositories` diff --git a/docs/user/guides/setup-single-sign-on-github-gitlab-bitbucket.rst b/docs/user/guides/setup-single-sign-on-github-gitlab-bitbucket.rst index 629d7811cdc..24d06e763cd 100644 --- a/docs/user/guides/setup-single-sign-on-github-gitlab-bitbucket.rst +++ b/docs/user/guides/setup-single-sign-on-github-gitlab-bitbucket.rst @@ -10,7 +10,7 @@ please read :doc:`/commercial/single-sign-on` Prerequisites ------------- -.. include:: /_includes/organization-permissions.rst +.. include:: /shared/organization-permissions.rst User setup ~~~~~~~~~~ diff --git a/docs/user/guides/setup-single-sign-on-google-email.rst b/docs/user/guides/setup-single-sign-on-google-email.rst index 51809f4104f..47022458061 100644 --- a/docs/user/guides/setup-single-sign-on-google-email.rst +++ b/docs/user/guides/setup-single-sign-on-google-email.rst @@ -10,7 +10,7 @@ please read :doc:`/commercial/single-sign-on` Prerequisites ------------- -.. include:: /_includes/organization-permissions.rst +.. include:: /shared/organization-permissions.rst User setup ~~~~~~~~~~ diff --git a/docs/user/img/screenshot-com-manual-import.png b/docs/user/img/screenshot-com-manual-import.png new file mode 100644 index 00000000000..1991716d796 Binary files /dev/null and b/docs/user/img/screenshot-com-manual-import.png differ diff --git a/docs/user/img/screenshot-com-ssh-keys.png b/docs/user/img/screenshot-com-ssh-keys.png new file mode 100644 index 00000000000..f24932f2bff Binary files /dev/null and b/docs/user/img/screenshot-com-ssh-keys.png differ diff --git a/docs/user/_includes/organization-permissions.rst b/docs/user/shared/organization-permissions.rst similarity index 100% rename from docs/user/_includes/organization-permissions.rst rename to docs/user/shared/organization-permissions.rst