Deploy keys

Deploy keys allow read-only or read-write access to your repositories by importing an SSH public key into your GitLab instance.

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:

• Project 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 provide access only to trusted users, and make sure that the allowed users have at least the Maintainer role in the GitLab project.

If this security implication is a concern for your organization, Deploy Tokens 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, 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 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.
• 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.
• 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 can add or enable a deploy key for a project repository:

1. On the top bar, select Menu > Projects and find your project.
2. On the left sidebar, select Settings > Repository.
3. Expand Deploy keys.
4. Specify a title for the new deploy key and paste your public SSH key.
5. Optional. To allow read-write access, select the Grant write permissions to this key checkbox. 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

After you add a key, it's enabled for this project by default and it appears 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.

After a key is added, you can edit it to update its title, or switch between read-only and read-write access.

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 is 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 allows for the integration of your repositories to secure, shared services, such as CI/CD.

Instance administrators can add public deploy keys:

1. On the top bar, select Menu > Admin.
2. On the left sidebar, select Deploy Keys.
3. Select New deploy key.

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 system. Users with a maintainer role or higher can authorize a public deploy key to start using it with the project.

NOTE: 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. 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, 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 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

Project maintainers and owners can remove or disable a deploy key for a project repository:

1. On the top bar, select Menu > Projects and find your project.
2. On the left sidebar, select Settings > Repository.
3. Expand Deploy keys.
4. Select Disable ({cancel}).

NOTE: Any service that relies on a deploy key stops working after that key is removed.

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 is deleted entirely from GitLab on removal.

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

There are a few scenarios where a deploy key will fail to push to a protected branch.

• 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 to the project of the protected branch.
• No one is selected in the "Allowed to push" section 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.