doc/user/project/deploy_keys/_index.md
{{< details >}}
{{< /details >}}
Use deploy keys to access repositories that are hosted in GitLab. In most cases, you use deploy keys to access a repository from an external host, like a build server or Continuous Integration (CI) server.
Depending on your needs, you might want to use a deploy token to access a repository instead.
| Attribute | Deploy key | Deploy token |
|---|---|---|
| Sharing | Shareable between multiple projects, even those in different groups. | Belong to a project or group. |
| Source | Public SSH key generated on an external host. | Generated on your GitLab instance, and is provided to users only at creation time. |
| Accessible resources | Git repository over SSH | Git repository over HTTP, package registry, and container registry. |
Deploy keys can't be used for Git operations if external authorization is enabled.
A deploy key has a defined scope when it is created:
You cannot change a deploy key's scope after creating it.
A deploy key is given a permission level when it is created:
You can change a deploy key's permission level after creating it. Changing a project deploy key's permissions only applies for the current project.
If a push that uses a deploy key triggers additional processes, the creator of the key must be authorized. For example:
Deploy keys are meant to facilitate non-human interaction with GitLab. For example, you can use a deploy key to grant permissions to a script that automatically runs on a server in your organization.
You should use a service account, and create the deploy key with the service account. If you use another user account to create deploy keys, that user is granted privileges that persist until the deploy key is revoked.
In addition:
As with all sensitive information, you should ensure only those who need access to the secret can read it. For human interactions, use credentials tied to users such as personal access tokens.
To help detect a potential secret leak, you can use the audit event feature.
To view the deploy keys available to a project:
The deploy keys available are listed:
The GitLab CLI provides a glab deploy-key list command.
Prerequisites:
read-write permission, select the Grant write permissions to this key
checkbox.A project deploy key is enabled when it is created. You can modify only a project deploy key's name and permissions. If the deploy key is enabled in more than one project, you can't modify the deploy key name.
The GitLab CLI provides a glab deploy-key add command.
{{< details >}}
{{< /details >}}
Prerequisites:
To create a public deploy key:
You can modify only a public deploy key's name.
Prerequisites:
To grant a public deploy key access to a project:
Prerequisites:
To edit the project access permissions of a deploy key:
To revoke a deploy key's access to a project, you can disable it. Any service that relies on a deploy key stops working when the key is disabled.
Prerequisites:
To disable a deploy key:
What happens to the deploy key when it is disabled depends on the following:
A deploy key is rejected when:
When a deploy key is rejected, it cannot be used for any repository operations, including pulls and pushes.
To resolve this issue:
There are a few scenarios where a deploy key fails to push to a protected branch.
This issue occurs because all deploy keys are associated to an account. Because 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.
To resolve this issue, you can use the deploy keys API to create deploy keys for project service account users, instead of for your own users:
Create a personal access token for that service account user. This token must have at least the api scope.
Use the deploy key API to create a deploy key for the service account user:
curl --request POST --header "PRIVATE-TOKEN: <service_account_access_token>" \
--header "Content-Type: application/json" \
--data '{"title": "My deploy key", "key": "ssh-rsa AAAA...", "can_push": "true"}' \
--url "https://gitlab.example.com/api/v4/projects/5/deploy_keys/"
If you need to find the keys that belong to a non-member or blocked user, you can use the Rails console to identify unusable deploy keys using a script similar to the following:
DeployKeysProject.with_write_access.find_each do |deploy_key_mapping|
project = deploy_key_mapping.project
deploy_key = deploy_key_mapping.deploy_key
user = deploy_key.user
access_checker = Gitlab::DeployKeyAccess.new(deploy_key, container: project)
# can_push_for_ref? tests if deploy_key can push to default branch, which is likely to be protected
can_push = access_checker.can_do_action?(:push_code)
can_push_to_default = access_checker.can_push_for_ref?(project.repository.root_ref)
next if access_checker.allowed? && can_push && can_push_to_default
if user.nil? || user.ghost?
username = 'none'
state = '-'
else
username = user.username
user_state = user.state
end
puts "Deploy key: #{deploy_key.id}, Project: #{project.full_path}, Can push?: " + (can_push ? 'YES' : 'NO') +
", Can push to default branch #{project.repository.root_ref}?: " + (can_push_to_default ? 'YES' : 'NO') +
", User: #{username}, User state: #{user_state}"
end
Deploy keys belong to a specific user and are rejected when the user is blocked or removed from the instance. To keep a deploy key working when a user is removed, change its owner to an active user.
If you have the fingerprint of the deploy key, you can change the user associated with a deploy key with the following commands:
k = Key.find_by(fingerprint: '5e:51:92:11:27:90:01:b5:83:c3:87:e3:38:82:47:2e')
k.user_id = User.find_by(username: 'anactiveuser').id
k.save()