部署令牌

使用部署密钥来访问托管在极狐GitLab 中的代码库。在大多数情况下，您可以使用部署密钥从外部主机（如构建服务器或持续集成（CI）服务器）访问代码库。

根据您的需求，您可能希望使用 部署令牌 来访问代码库。

如果启用了 外部授权，则无法使用部署密钥进行 Git 操作。

范围#

创建部署密钥时，会定义其范围：

• 项目部署密钥： 访问权限仅限于选定的项目。
• 公共部署密钥： 可以授予对极狐GitLab 实例中 任何 项目的访问权限。每个项目的访问权限必须由至少具有维护者角色的用户授予。

创建后，您无法更改部署密钥的范围。

权限#

创建部署密钥时，会赋予其权限级别：

• 只读： 只读部署密钥只能从代码库读取。
• 读写： 读写部署密钥可以从代码库读取和写入。

创建后，您可以更改部署密钥的权限级别。更改项目部署密钥的权限仅适用于当前项目。

如果使用部署密钥的推送触发了其他流程，则密钥的创建者必须被授权。例如：

• 当使用部署密钥将提交推送到 受保护分支 时，部署密钥的创建者必须有权访问该分支。
• 当使用部署密钥推送提交触发 CI/CD 流水线时，部署密钥的创建者必须能够访问 CI/CD 资源，包括受保护的环境和密钥变量。

安全影响#

部署密钥旨在促进与极狐GitLab 的非人工交互。例如，您可以使用部署密钥授予权限给在您组织的服务器上自动运行的脚本。

您应该使用 服务账户，并使用服务账户创建部署密钥。如果使用其他用户账户创建部署密钥，则该用户将被授予权限，直到撤销部署密钥。

此外：

• 即使创建它们的用户被移除出群组或项目，部署密钥仍然有效。
• 即使用户被降级或移除，部署密钥的创建者仍然保留对群组或项目的访问权限。
• 当在受保护分支规则中指定了部署密钥时，部署密钥的创建者：
  • 获得对受保护分支和部署密钥本身的访问权限。
  • 如果部署密钥具有读写权限，可以推送到受保护分支。即使分支受到对所有用户的更改保护，这也是成立的。
• 如果部署密钥的创建者被阻止或从实例中移除，该用户仍然可以从群组或项目中拉取更改，但不能推送。

与所有敏感信息一样，您应确保只有需要访问密钥的人才能读取它。对于人工交互，请使用与用户绑定的凭据，如个人访问令牌。

为了帮助检测潜在的密钥泄漏，您可以使用 审计事件 功能。

查看部署密钥#

要查看项目可用的部署密钥：

1. 在左侧边栏中，选择 搜索或前往 并找到您的项目。
2. 选择 设置 > 代码库。
3. 展开 部署密钥。

列出的可用部署密钥：

• 启用的部署密钥： 可以访问项目的部署密钥。
• 私有可访问部署密钥： 没有访问项目的项目部署密钥。
• 公共可访问部署密钥： 没有访问项目的公共部署密钥。

创建项目部署密钥#

先决条件：

• 您必须至少具有项目的维护者角色。
• 生成一个 SSH 密钥对。将私有 SSH 密钥放在需要访问代码库的主机上。

1. 在左侧边栏中，选择 搜索或前往 并找到您的项目。
2. 选择 设置 > 代码库。
3. 展开 部署密钥。
4. 选择 添加新密钥。
5. 完成字段。
6. 可选：要授予 读写 权限，请选择 授予此密钥写权限 复选框。
7. 可选：更新 过期日期。

创建项目部署密钥时，它会被启用。您只能修改项目部署密钥的名称和权限。如果部署密钥在多个项目中启用，则无法修改其名称。

创建公共部署密钥#

先决条件：

• 您必须具有实例的管理员访问权限。
• 您必须 生成一个 SSH 密钥对。
• 您必须将私有 SSH 密钥放在需要访问代码库的主机上。

要创建公共部署密钥：

1. 在左侧边栏底部，选择 管理员。
2. 选择 部署密钥。
3. 选择 新部署密钥。
4. 完成字段。
   • 为 名称 使用有意义的描述。例如，包含使用公共部署密钥的外部主机或应用程序的名称。

您只能修改公共部署密钥的名称。

授予项目对公共部署密钥的访问权限#

先决条件：

• 您必须至少具有项目的维护者角色。

要授予公共部署密钥对项目的访问权限：

1. 在左侧边栏中，选择 搜索或前往 并找到您的项目。
2. 选择 设置 > 代码库。
3. 展开 部署密钥。
4. 选择 公共可访问部署密钥。
5. 在密钥的行中，选择 启用。
6. 要授予公共部署密钥读写权限：
   1. 在密钥的行中，选择 编辑 (
      )。
   2. 选择 授予此密钥写权限 复选框。

编辑部署密钥的项目访问权限#

先决条件：

• 您必须至少具有项目的维护者角色。

要编辑部署密钥的项目访问权限：

1. 在左侧边栏中，选择 搜索或前往 并找到您的项目。
2. 选择 设置 > 代码库。
3. 展开 部署密钥。
4. 在密钥的行中，选择 编辑 (
   )。
5. 选择或清除 授予此密钥写权限 复选框。

撤销部署密钥的项目访问权限#

要撤销项目对部署密钥的访问权限，您可以禁用它。任何依赖于部署密钥的服务在密钥被禁用时将停止工作。

先决条件：

• 您必须至少具有项目的维护者角色。

要禁用部署密钥：

1. 在左侧边栏中，选择 搜索或前往 并找到您的项目。
2. 选择 设置 > 代码库。
3. 展开 部署密钥。
4. 选择 禁用 (
   )。

禁用后，部署密钥的处理取决于以下几点：

• 如果密钥是公开可访问的，它将从项目中移除，但仍可在 公共可访问部署密钥 选项卡中使用。
• 如果密钥是私有可访问的且仅在此项目中使用，则它将被删除。
• 如果密钥是私有可访问的并且也在其他项目中使用，则它将从项目中移除，但仍可在 私有可访问部署密钥 选项卡中使用。

故障排除#

部署密钥无法推送到受保护分支#

在某些情况下，部署密钥无法推送到 受保护分支。

• 与部署密钥关联的所有者没有受保护分支项目的成员资格。
• 与部署密钥关联的所有者的项目成员权限低于查看项目代码所需的权限。
• 部署密钥没有项目的读写权限。
• 部署密钥已被撤销。
• 在受保护分支的允许推送和合并部分中未选择任何人。

此问题的发生是因为所有部署密钥都与一个账户关联。由于账户的权限可能会更改，这可能导致一个曾经可以工作的部署密钥突然无法推送到受保护分支。

要解决此问题，您可以使用部署密钥 API 为项目服务账户用户创建部署密钥，而不是为您自己的用户创建：

1. 创建服务账户用户。

2. 为该服务账户用户创建个人访问令牌。该令牌必须至少具有 api 范围。

3. 邀请服务账户用户加入项目。

4. 使用部署密钥 API 为服务账户用户创建部署密钥：

   shell
   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"}' \
   "https://gitlab.example.com/api/v4/projects/5/deploy_keys/"

识别与非成员和被阻止用户关联的部署密钥#

如果您需要查找属于非成员或被阻止用户的密钥，可以使用 Rails 控制台 使用类似以下的脚本识别不可用的部署密钥：

ruby
1ghost_user_id = Users::Internal.ghost.id
2
3DeployKeysProject.with_write_access.find_each do |deploy_key_mapping|
4  project = deploy_key_mapping.project
5  deploy_key = deploy_key_mapping.deploy_key
6  user = deploy_key.user
7
8  access_checker = Gitlab::DeployKeyAccess.new(deploy_key, container: project)
9
10  # can_push_for_ref? tests if deploy_key can push to default branch, which is likely to be protected
11  can_push = access_checker.can_do_action?(:push_code)
12  can_push_to_default = access_checker.can_push_for_ref?(project.repository.root_ref)
13
14  next if access_checker.allowed? && can_push && can_push_to_default
15
16  if user.nil? || user.id == ghost_user_id
17    username = 'none'
18    state = '-'
19  else
20    username = user.username
21    user_state = user.state
22  end
23
24  puts "Deploy key: #{deploy_key.id}, Project: #{project.full_path}, Can push?: " + (can_push ? 'YES' : 'NO') +
25       ", Can push to default branch #{project.repository.root_ref}?: " + (can_push_to_default ? 'YES' : 'NO') +
26       ", User: #{username}, User state: #{user_state}"
27end

设置部署密钥的所有者#

部署密钥属于特定用户，当用户被阻止或从实例中移除时将被停用。要在用户被移除时保持部署密钥有效，请将其所有者更改为一个活动用户。

如果您拥有部署密钥的指纹，可以使用以下命令更改与部署密钥关联的用户：

shell
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()