diff options
Diffstat (limited to 'doc/user/project/deploy_keys/index.md')
| -rw-r--r-- | doc/user/project/deploy_keys/index.md | 90 |
1 files changed, 52 insertions, 38 deletions
diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index e9a38f91677..61dccf1cb1b 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -10,9 +10,10 @@ type: howto, reference Deploy keys allow read-only or read-write access to your repositories by importing an SSH public key into your GitLab instance. -This is useful, for example, for cloning repositories to your Continuous -Integration (CI) server. By using deploy keys, you don't have to set up a -fake user account. +Deploy keys streamline interactions between your GitLab repository and another +machine. For example, setting up a deploy key allows secure cloning of your +repositories to a Continuous Integration (CI) server without setting up a fake +user account. There are two types of deploy keys: @@ -63,11 +64,12 @@ help you access a repository, but there are some notables differences between th - 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. +- A deploy key is an SSH key you generate on the **remote machine**. A deploy + token, on the other hand, 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. @@ -115,9 +117,9 @@ project, and if you then update the access level for this key from `read-only` t ### 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. +Public deploy keys allow `read-only` or `read-write` access to any repository in +your GitLab instance. This allows for the integration of your repositories to +secure, shared services, such as CI/CD. Instance administrators can add public deploy keys: @@ -125,32 +127,37 @@ Instance administrators can add public deploy keys: 1. On the left sidebar, select **Deploy Keys**. 1. Select **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. +Make sure your new key has a meaningful title. This title is the primary +way for project maintainers and owners to identify the correct public deploy key +to add to a repository or project. For example, the key you set up might be +intended to give access to a SaaS CI/CD instance. In this case use the name of +that service in the key title if that is all the key is used for.  -After adding a key, it's 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. +After adding a key, it's available to any shared system. Users with a maintainer role or +higher can [authorize a public deploy key](#project-deploy-keys) to start using +it with the project. 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. +The **Publicly accessible deploy keys** tab in a 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. +Public deploy keys can provide greater security compared to project deploy keys. +This is because the administrator of the target integrated system is the only +entity who needs to know or configure the key value. -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. +When creating a Public deploy key, consider what scope and permissions are +required for it across the entire GitLab instance. For very narrow usage, such +as a single specific service, a `read-only` deploy key tied to this service is +best. If the service entails broader usage across the instance, a +deploy key with full `read-write` access is more appropriate. 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. +Adding a public deploy key **does not** immediately expose any repository +to the remote machine. Access to a project is only given when a project +maintainer chooses to make use of a deploy key in the project's +configuration. ## How to disable deploy keys @@ -162,22 +169,29 @@ can remove or disable a deploy key for a project repository: 1. Select the **{remove}** or **{cancel}** button. NOTE: -If anything relies on the removed deploy key, it will stop working once removed. +Any service that relies on a deploy key stops working after that key is removed. -If the key is **publicly accessible**, it will be removed from the project, but still available under **Publicly accessible deploy keys**. +If the key is **publicly accessible**, it is removed from the project, but can +still be found under **Publicly accessible deploy keys**. -If the key is **privately accessible** and only in use by this project, it will deleted. +If the key is **privately accessible** and only in use by this project, it is +deleted entirely from GitLab on removal. -If the key is **privately accessible** and in use by other projects, it will be removed from the project, but still available under **Privately accessible deploy keys**. +If the key is **privately accessible** and also in use by other projects, it is +removed from the project, but still available under **Privately accessible +deploy keys**. ## Troubleshooting ### Deploy key cannot push to a protected branch -If the owner of this deploy key doesn't have access to a [protected -branch](../protected_branches.md), then this deploy key doesn'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#configure-a-protected-branch) -means that no users **and** no services using deploy keys can push to that selected branch. +There are a few scenarios where a deploy key will fail to push to a [protected +branch](../protected_branches.md). -Refer to [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/30769) for more information. +- The owner associated to a deploy key does not have access to the protected branch. +- The owner associated to a deploy key does not have [membership](../members/index.md) to the project of the protected branch. +- **No one** is selected in [the "Allowed to push" section](../protected_branches.md#configure-a-protected-branch) of the protected branch. + +All deploy keys are associated to an account. Since the permissions for an account can change, this might lead to scenarios where a deploy key that was working is suddenly unable to push to a protected branch. + +We recommend you create a service account, and associate a deploy key to the service account, for projects using deploy keys. |