Updated Deploy Keys documentation

Rewrote parts of the Deploy Keys documentation.
Uploaded image used as description.

doc/ssh/README.md

@@ -119,7 +119,7 @@ Enter file in which to save the key (/home/user/.ssh/id_rsa):
 For guidance, proceed to the [common steps](#common-steps-for-generating-an-ssh-key-pair).
 
 NOTE: **Note:**
-If your have OpenSSH version 7.8 or below, consider the problems associated
+If you have OpenSSH version 7.8 or below, consider the problems associated
 with [encoding](#rsa-keys-and-openssh-from-versions-65-to-78).
 
 ### Common steps for generating an SSH key pair
@@ -370,80 +370,7 @@ git remote set-url origin git@<user_1.gitlab.com>:gitlab-org/gitlab.git
 
 ## Deploy keys
 
-Deploy keys allow read-only or read-write (if enabled) access to one or
-multiple repositories with a single SSH key pair.
-
-This is useful for cloning repositories to your Continuous
-Integration (CI) server. By using deploy keys, you don't have to set up a
-dummy user account.
-
-If you don't have a key pair, you might want to use a
-[deploy token](../user/project/deploy_tokens/index.md#deploy-tokens) instead.
-
-### Per-repository deploy keys
-
-Project maintainers and owners can add a deploy key for a repository.
-
-1. Navigate to the project's **Settings > Repository** page.
-1. Expand the **Deploy Keys** section.
-1. Specify a title for the new deploy key and paste a public SSH key.
-
-After this, the machine that uses the corresponding private SSH key has read-only or
-read-write (if enabled) access to the project.
-
-You can't add the same deploy key twice using the form.
-If you want to add the same key to another project, please enable it in the
-list that says **Deploy keys from projects available to you**. All the deploy
-keys of all the projects you have access to are available. This project
-access can happen through being a direct member of the project, or through
-a group.
-
-Deploy keys can be shared between projects, you just need to add them to each
-project.
-
-### Global shared deploy keys
-
-Global Shared Deploy keys allow read-only or read-write access to
-any repository in the entire GitLab installation.
-
-This is useful for integrating repositories to secured, shared Continuous
-Integration (CI) services or other shared services.
-GitLab administrators can set up the Global Shared Deploy key in GitLab and
-add the private key to any shared systems. Individual repositories opt into
-exposing their repository using these keys when a project maintainers (or higher)
-authorizes a Global Shared Deploy key to be used with their project.
-
-Global Shared Keys can provide greater security compared to Per-Project Deploy
-Keys since an administrator of the target integrated system is the only one
-who needs to know and configure the private key.
-
-GitLab administrators set up Global Deploy keys in the Admin Area under the
-section **Deploy Keys**. Ensure keys have a meaningful title as that will be
-the primary way for project maintainers and owners to identify the correct Global
-Deploy key to add. For instance, if the key gives access to a SaaS CI instance,
-use the name of that service in the key name if that is all it is used for.
-When creating Global Shared Deploy keys, give some thought to the granularity
-of keys - they could be of very narrow usage such as just a specific service or
-of broader usage for something like "Anywhere you need to give read access to
-your repository".
-
-Once a GitLab administrator adds the Global Deployment key, project maintainers
-and owners can add it by:
-
-1. Navigate to the project's **Settings > Repository** page.
-1. Expanding the **Deploy Keys** section.
-1. Clicking **Enable** next to the appropriate key listed under
-   **Public deploy keys available to any project**.
-
-NOTE: **Note:**
-The heading **Public deploy keys available to any project** only appears
-if there is at least one Global Deploy Key configured.
-
-CAUTION: **Warning:**
-Defining Global Deploy Keys does not expose any given repository via
-the key until that repository adds the Global Deploy Key to their project.
-In this way the Global Deploy Keys enable access by other systems, but do
-not implicitly give any access just by setting them up.
+Read the [documentation on Deploy Keys](../user/project/deploy_keys/index.md).
 
 ## Applications
 

doc/user/project/deploy_keys/index.md

+# Deploy Keys
+
+Deploy keys allow read-only or read-write (if enabled) access to one or
+more repositories, by importing an SSH public key to your GitLab instance.
+
+This is useful for cloning repositories to your Continuous
+Integration (CI) server. By using deploy keys, you don't have to set up a
+dummy user account.
+
+There are two types of deploy keys:
+
+- [Project deploy keys](#project-deploy-keys)
+- [Public deploy keys](#public-deploy-keys)
+
+## Key details on deploy keys
+
+Deploy Keys allow a remote machine (VM, physical, and so on) to access a GitLab
+repository with just a few steps. If you want a remote machine to interact with a GitLab
+repository in automation, it's a simple solution.
+
+A drawback is that your repository could become vulnerable if a remote machine is compromised
+by a hacker. You should limit access to the remote machine before a deploy key is
+enabled on your repository. A good rule to follow is to access only to trusted users,
+and make sure that the allowed users have [maintainer permissions or higher](../../permissions.md)
+in the GitLab project.
+
+If this security implication is a concern for your organization,
+[Deploy Tokens](../deploy_tokens/index.md) works as an alternative, but with more
+security control.
+
+## Deploy Keys Permissions
+
+You can choose the access level of a deploy key when you enable it on a project:
+
+- `read-only`: The deploy key can read a repository.
+- `read-write`: The deploy key can read a repository and write to it.
+
+Project maintainers and owners can activate and deactivate deploy keys.
+They can also add their own deploy keys and enable them for this project.
+
+When a `write-access` deploy key is used to push a commit, GitLab checks if
+the **creator** of the deploy key has permission to access the resource. For example:
+
+- When a deploy key is used to push a commit to a [protected branch](../protected_branches.md),
+  the **creator** of the deploy key must have access to the branch.
+- When a deploy key is used to push a commit that triggers a CI/CD pipelines, the **creator** of
+  the deploy key must have access to the CI/CD resources (like protected environments, secret variables, and so on).
+- If the **creator** of a deploy key does not have permissions to read a project's
+  repository, the deploy key _might_ encounter an error during the process.
+
+## Differences between deploy keys and deploy tokens
+
+Both deploy keys and [deploy tokens](../deploy_tokens/index.md#deploy-tokens) can
+help you access a repository, but there are some notables differences between them:
+
+- Deploy keys are shareable between projects that are not related or don't even
+  belong to the same group. Deploy tokens belong to either a project or
+  [a group](../deploy_tokens/index.md#group-deploy-token).
+- A deploy key is an SSH key you need to generate yourself on your machine. A deploy
+  token is generated by your GitLab instance, and is provided to users only once
+  (at creation time).
+- A deploy key is valid as long as it's registered and enabled. Deploy tokens can
+  be time-sensitive, as you can control their validity by setting an expiration date to them.
+- You can't log in to a registry with deploy keys, or perform read / write operations
+  on it, but this [is possible with deploy tokens](../deploy_tokens/index.md#gitlab-deploy-token).
+- You need an SSH key pair to use deploy keys, but not deploy tokens.
+
+## How to enable Deploy Keys
+
+### Project deploy keys
+
+[Project maintainers and owners](../../permissions.md#project-members-permissions)
+can add or enable a deploy key for a project repository:
+
+1. Navigate to the project's **Settings > Repository** page.
+1. Expand the **Deploy Keys** section.
+1. Specify a title for the new deploy key and paste your public SSH key.
+1. (Optional) Check **Write access allowed** to allow `read-write` access. Leave it unchecked for `read-only` access.
+
+There are three lists of Project Deploy Keys:
+
+- Enabled deploy keys
+- Privately accessible deploy keys
+- Public accessible deploy keys
+
+![Deploy Keys section](img/deploy_keys_v13_0.png)
+
+After you add a key, it will be enabled for this project by default, and it'll appear
+in the **Enabled deploy keys** tab.
+
+In the **Privately accessible deploy keys** tab, you can enable a private key which
+has been already imported in a different project. If you have access to these keys,
+it's because you have either:
+
+- Previously uploaded the keys yourself in a different project.
+- You are a maintainer or owner of the other project where the keys were imported.
+
+In the **Publicly accessible deploy keys** tab, you can enable
+keys that were [made available to your entire GitLab instance](#public-deploy-keys).
+
+After a key is added, you can edit it to update its title, or switch between `read-only`
+and `read-write` access.
+
+NOTE: **Note:**
+If you have enabled a privately or publicly accessible or deploy key for your
+project, and if you then update the access level for this key from `read-only` to
+`read-write`, the change will be only for the **current project**.
+
+### Public deploy keys
+
+Public deploy keys allow `read-only` or `read-write`
+access to any repository in your GitLab instance. This is useful for integrating
+repositories to secure, shared services, such as CI/CD.
+
+Instance administrators can add public deploy keys:
+
+1. Go to **Admin Area** (**{admin}**) **> Deploy Keys**.
+1. Click on **New deploy key**.
+
+   Make sure your new key has a meaningful title, as it is the primary way for project
+   maintainers and owners to identify the correct public deploy key to add. For example,
+   if the key gives access to a SaaS CI/CD instance, use the name of that service
+   in the key name if that is all the key is used for.
+
+![Public Deploy Keys section](img/public_deploy_key_v13_0.png)
+
+After adding a key, it will be available to any shared systems. Project maintainers
+or higher can [authorize a public deploy key](#project-deploy-keys) to start using it with the project.
+
+NOTE: **Note:**
+The **Publicly accessible deploy keys** tab within Project's CI/CD settings only appears
+if there is at least one Public deploy key configured.
+
+Public deploy keys can provide greater security compared to project deploy keys, as
+the administrator of the target integrated system is the only one who needs to know the key value,
+or configure it.
+
+When creating a Public deploy key, determine whether or not it can be defined for
+very narrow usage, such as just a specific service, or if it needs to be defined for
+broader usage, such as full `read-write` access for all services.
+
+CAUTION: **Warning:**
+Adding a public deploy key does not immediately expose any repository to it. Public
+deploy keys enable access from other systems, but access is not given to any project
+until a project maintainer chooses to make use of it.
+
+## Troubleshooting
+
+### Deploy Key cannot push to a protected branch
+
+If the owner of this deploy key does not have access to a [protected
+branch](../protected_branches.md), then this deploy key won't have access to
+the branch either. In addition to this, choosing the **No one** value in
+[the "Allowed to push" section](../protected_branches.md#configuring-protected-branches)
+means that no users **and** no services using deploy keys can push to that selected branch.
+
+Refer to [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/30769) for more information.