From 8c7f4e9d5f36cff46365a7f8c4b9c21578c1e781 Mon Sep 17 00:00:00 2001 From: GitLab Bot Date: Thu, 18 Jun 2020 11:18:50 +0000 Subject: Add latest changes from gitlab-org/gitlab@13-1-stable-ee --- doc/user/project/deploy_keys/index.md | 164 ++++++++++++++++++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 doc/user/project/deploy_keys/index.md (limited to 'doc/user/project/deploy_keys/index.md') diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md new file mode 100644 index 00000000000..32d3eab5e62 --- /dev/null +++ b/doc/user/project/deploy_keys/index.md @@ -0,0 +1,164 @@ +--- +stage: Release +group: Progressive Delivery +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +type: howto, reference +--- + +# 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. -- cgit v1.2.3