部署令牌

您可以使用部署令牌来启用部署任务的认证，这独立于用户账号。在大多数情况下，您可以从外部宿主机使用部署令牌，比如构建服务器或 CI/CD 服务器。

有了部署令牌，自动化任务可以：

  • 克隆 Git 仓库
  • 拉取或推送极狐GitLab 容器镜像仓库。
  • 拉取或推送极狐GitLab 软件包仓库。ull from and push to a GitLab package registry.

部署令牌是一对值：

  • 用户名：HTTP 认证框架中的 username。默认的用户名格式为 gitlab+deploy-token-{n}。当您创建部署令牌时，您可以指定自定义的用户名。
  • 令牌： HTTP 认证框架中的 password。

部署令牌不支持 SSH 认证.

针对以下端点，您可以为 HTTP 认证使用部署令牌：

  • 极狐GitLab 软件包仓库公共 API。
  • Git 命令。

您可以在项目或群组上创建部署令牌：

  • 项目部署令牌：权限仅限于项目
  • 群组部署令牌：权限仅限于群组中的所有项目。

默认情况下，部署令牌不会过期。当然，您也可以在创建的时候设置过期选项。到期时间为该日期的协调世界时（UTC）午夜。

caution 如果启用了外部认证，您不能够为 Git 操作和软件包仓库操作使用心得或即有的部署令牌。

范围

部署令牌的范围决定了它可以操作的操作。

范围 描述
read_repository 使用 git clone 仓库的只读权限。
read_registry 项目容器镜像仓库的只读权限。
write_registry 项目容器镜像仓库的写权限。如要推送镜像，您需要读写权限。
read_package_registry 项目软件包仓库的只读权限。
write_package_registry 项目软件包仓库的读权限。

极狐GitLab 部署令牌

  • 群组级别的 gitlab-deploy-token 支持引入于极狐GitLab 15.1，使用名为 ci_variable_for_group_gitlab_deploy_token 功能标志。默认启用。
  • ci_variable_for_group_gitlab_deploy_token 功能标志在极狐GitLab 15.4 中被移除。

极狐GitLab 部署令牌是一种特殊的部署令牌。如果您创建了一个名为 gitlab-deploy-token 的部署令牌，该部署令牌会自动暴露给项目 CI/CD 作业的变量：

  • CI_DEPLOY_USER：用户名
  • CI_DEPLOY_PASSWORD：令牌

比如，要使用极狐GitLab 令牌登录极狐GitLab 容器镜像仓库：

echo "$CI_DEPLOY_PASSWORD" | docker login $CI_REGISTRY -u $CI_DEPLOY_USER --password-stdin
note 在极狐GitLab 15.0 及早期版本，gitlab-deploy-token 部署令牌的特殊处理并不对群组部署令牌生效。要使群组部署令牌对 CI/CD 作业可用，您需要在 设置 > CI/CD > 变量 中将CI_DEPLOY_USER 和 CI_DEPLOY_PASSWORD CI/CD 变量设置群组部署令牌的名称和令牌。

当在群组中定义 gitlab-deploy-token 时，CI_DEPLOY_USER 和 CI_DEPLOY_PASSWORD CI/CD 变量在群组中的所有子项目都可用。

极狐GitLab 部署令牌安全

极狐GitLab 部署令牌是长期的，因此攻击者对它们更感兴趣。

要想防止部署令牌的泄露，您应该配置您的runners，让它们更安全：

  • 如果机器被复用，则要避免使用 Docker 的 privileged 模式。
  • 当在同一个机器上运行作业时，则要避免使用 shell 执行器。

不安全的极狐GitLab Runner 配置增加了攻击者从其他作业窃取令牌的风险。

极狐GitLab 公共 API

部署令牌不能和极狐GitLab 公共 API 一起使用。然而，您可以和其他端点一起使用部署令牌，比如软件包镜像仓库。您可以区分哪些属于软件包仓库的端点，因为它们的 URL 有明显的 packages/<format> 字符。比如：https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt。更多详情，可以查看认证仓库。

创建项目部署密钥

创建一个部署令牌来自动化那些可以和用户账号独立的部署任务。

先决条件：

  • 要创建群组部署令牌，您必须具有群组的拥有者角色。
  • 要创建项目部署令牌，您必须至少具有项目的维护者角色。
  1. 在左侧边栏中，选择 搜索或转到 并找到您的项目。
  2. 在左侧边栏中，选择 设置 > 仓库。
  3. 展开 部署令牌。
  4. 选择 添加令牌。
  5. 完成字段，并选择期望的范围。
  6. 选择 创建部署令牌。

记录并保存好 部署令牌的值。在您离开或者刷新页面后，您将无法再次访问它。

撤销部署令牌

当不再需要部署令牌时，可以撤销它。

先决条件：

  • 要撤销群组的部署令牌，您必须具有群组的拥有者角色。
  • 要撤销项目的部署令牌，您必须至少具有项目的维护者角色。

要撤销部署令牌：

  1. 在左侧导航栏，选择 搜索或转到 并找到您的项目或群组。
  2. 选择 设置 > 仓库。
  3. 展开 部署令牌。
  4. 在 激活的部署令牌 部分，选择您想要撤销的令牌，然后点击 撤销。

克隆仓库

您可以使用部署令牌来克隆仓库。

先决条件：

  • 一个具有 read_repository 范围的部署令牌。

使用部署令牌克隆仓库的示例如下：

git clone https://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git

从容器镜像仓库拉取镜像

您可以使用部署令牌来从容器镜像仓库拉取镜像。

先决条件：

  • 一个具有 read_registry 范围的部署令牌。

使用部署令牌从容器镜像仓库拉取镜像的示例如下：

echo "$DEPLOY_TOKEN" | docker login -u <username> --password-stdin registry.example.com
docker pull $CONTAINER_TEST_IMAGE

推送镜像到容器镜像仓库

您可以使用部署令牌来推送镜像到容器镜像仓库。

先决条件：

  • 一个具有 read_registry 和 write_registry 范围的部署令牌。

使用部署令牌将镜像推送到容器镜像仓库的示例如下：

echo "$DEPLOY_TOKEN" | docker login -u <username> --password-stdin registry.example.com
docker push $CONTAINER_TEST_IMAGE

从软件包仓库拉取软件包

您可以使用部署令牌来从软件包仓库拉取软件包。

先决条件：

  • 一个具有 read_package_registry 范围的部署令牌。

针对您选择的软件包类型，需要遵循对应的部署令牌认证说明。

从极狐GitLab 仓库安装 NuGet 软件包的示例如下：

nuget source Add -Name GitLab -Source "https://gitlab.example.com/api/v4/projects/10/packages/nuget/index.json" -UserName <username> -Password <deploy_token>
nuget install mypkg.nupkg

推送软件包到软件包仓库

您可以使用部署令牌来推送软件包到软件包仓库。

先决条件：

  • 一个具有 write_package_registry 范围的部署令牌。

针对您选择的软件包类型，需要遵循对应的部署令牌认证说明。

发布 NuGet 软件包到软件包仓库的示例如下：

nuget source Add -Name GitLab -Source "https://gitlab.example.com/api/v4/projects/10/packages/nuget/index.json" -UserName <username> -Password <deploy_token>
nuget push mypkg.nupkg -Source GitLab

从依赖代理拉取镜像

您可以使用部署令牌来从依赖代理拉取镜像。

先决条件：

  • 一个具有 read_registry 和 write_registry 范围的部署令牌。

遵循依赖代理的认证说明。