个人访问令牌

个人访问令牌可以作为 OAuth2 的替代方案，用于：

• 对 GitLab API 进行身份验证。
• 使用 HTTP Basic Authentication 对 Git 进行身份验证。

在这两种情况下，你都可以使用个人访问令牌代替密码进行身份验证。用户名不会作为身份验证过程的一部分进行评估。

个人访问令牌：

• 当启用 双因素身份验证 (2FA) 或 SAML 时是必需的。
• 与 GitLab 用户名一起使用，用于对需要用户名的 GitLab 功能进行身份验证。例如， GitLab 管理的 Terraform 状态后端 和 Docker 容器注册表。
• 与 项目访问令牌 和 组访问令牌 类似，但它们附加到用户而不是项目或组。

有关如何使用个人访问令牌对 API 进行身份验证的示例，请参阅 API 文档。

或者，GitLab 管理员可以使用 API 创建 模拟令牌。 使用模拟令牌以特定用户身份进行自动化身份验证。

创建个人访问令牌

你可以创建任意数量的个人访问令牌。

1. 在左侧边栏，选择你的头像。

2. 选择 编辑个人资料。

3. 在左侧边栏，选择 访问令牌。

4. 选择 添加新令牌。

5. 在 令牌名称 中，输入令牌的名称。

6. 可选。在 令牌描述 中，输入令牌的描述。

7. 在 过期日期 中，输入令牌的过期日期。

   • 令牌在该日期的午夜 UTC 过期。过期日期为 2024-01-01 的令牌在 2024-01-01 00:00:00 UTC 过期。
   • 如果你不输入过期日期，过期日期将自动设置为当前日期的 365 天后。
   • 默认情况下，此日期最多可以是当前日期的 365 天后。在 GitLab 17.6 或更高版本中，你可以 将此限制延长到 400 天。

8. 选择所需的 权限范围。

9. 选择 创建个人访问令牌。

将个人访问令牌保存在安全的地方。离开页面后，你将无法再访问该令牌。

预填充个人访问令牌详情

你可以通过将名称、描述和权限范围列表附加到 URL 来预填充个人访问令牌的详情。例如：

https://gitlab.example.com/-/user_settings/personal_access_tokens?name=Example+Access+token&description=My+description&scopes=api,read_user

撤销或轮换个人访问令牌

随时可以使用 UI 撤销或（在 GitLab 17.7 及更高版本中）轮换个人访问令牌。

1. 在左侧边栏，选择你的头像。

2. 选择 编辑个人资料。

3. 在左侧边栏，选择 访问令牌。

4. 在活动令牌旁边，选择垂直省略号（ ）。

5. 选择 撤销（ ）或 轮换（ ）。

6. 在确认对话框中，选择 撤销 或 轮换。

   这些操作无法撤销。任何依赖于被撤销或轮换的访问令牌的工具将停止工作。

禁用个人访问令牌

先决条件：

• 你必须是管理员。

根据你的 GitLab 版本，你可以使用应用程序设置 API 或管理 UI 来禁用个人访问令牌。

使用应用程序设置 API

在 GitLab 15.7 及更高版本中，你可以使用 应用程序设置 API 中的 disable_personal_access_tokens 属性 来禁用个人访问令牌。

使用管理 UI

在 GitLab 17.3 及更高版本中，你可以使用管理 UI 来禁用个人访问令牌：

1. 在左侧边栏，底部，选择 管理。
2. 选择 设置 > 常规。
3. 展开 可见性和访问控制。
4. 选择 禁用个人访问令牌 复选框。
5. 选择 保存更改。

为企业用户禁用个人访问令牌

先决条件：

• 你必须拥有企业用户所属组的所有者角色。

禁用组的 企业用户 的个人访问令牌：

• 阻止企业用户创建新的个人访问令牌。即使企业用户也是该组的管理员，此行为也适用。
• 禁用企业用户的现有个人访问令牌。

要禁用企业用户的个人访问令牌：

1. 在左侧边栏，选择 搜索或跳转 并找到你的组。
2. 选择 设置 > 常规。
3. 展开 权限和组功能。
4. 在 个人访问令牌 下，选择 禁用个人访问令牌。
5. 选择 保存更改。

当你删除或阻止企业用户账户时，他们的个人访问令牌会自动被撤销。

查看令牌使用信息

令牌使用信息会定期更新。令牌上次使用的时间每 10 分钟更新一次，最近使用的 IP 地址每分钟更新一次。当令牌：

• 对 REST 或 GraphQL API 进行身份验证。
• 执行 Git 操作。

GitLab 认为令牌被使用。

要查看令牌上次使用的时间，以及使用令牌的 IP 地址：

1. 在左侧边栏，选择你的头像。
2. 选择 编辑个人资料。
3. 在左侧边栏，选择 访问令牌。
4. 在 活动个人访问令牌 区域，查看相关令牌的 上次使用 日期和 上次使用的 IP。 上次使用的 IP 显示最近五个不同的 IP 地址。

个人访问令牌权限范围

个人访问令牌可以根据分配的权限范围执行操作。

访问令牌过期

个人访问令牌在你定义的日期午夜 00:00 AM UTC 过期。过期日期为 2024-01-01 的令牌在 2024-01-01 00:00:00 UTC 过期。

• GitLab 每天在 1:00 AM UTC 运行检查，以识别即将过期的个人访问令牌。这些令牌的所有者会收到 电子邮件通知。
• GitLab 每天在 02:00 AM UTC 运行检查，以识别在当前日期过期的个人访问令牌。这些令牌的所有者会收到电子邮件通知。
• 在 GitLab Ultimate 中，管理员可以 限制访问令牌的允许生命周期。如果未设置，个人访问令牌的最大允许生命周期为 365 天。在 GitLab 17.6 或更高版本中，你可以 将此限制延长到 400 天。
• 在 GitLab Free 和 Premium 中，个人访问令牌的最大允许生命周期为 365 天。在 GitLab 17.6 或更高版本中，你可以 将此限制延长到 400 天。
• 如果在创建个人访问令牌时未设置过期日期，过期日期将设置为令牌的 最大允许生命周期。 如果未设置最大允许生命周期，默认过期日期为创建日期的 365 天后。

你的现有个人访问令牌是否自动应用过期日期取决于你拥有的 GitLab 产品，以及你何时升级到 GitLab 16.0 或更高版本：

• 在 GitLab.com 上，在 16.0 里程碑期间，没有过期日期的现有个人访问令牌自动被赋予当前日期后 365 天的过期日期。
• 在 GitLab 自托管上，如果你从 GitLab 15.11 或更早版本升级到 GitLab 16.0 或更高版本：
  • 在 2024 年 7 月 23 日或之前，没有过期日期的现有个人访问令牌自动被赋予当前日期后 365 天的过期日期。 这是一个破坏性更改。
  • 在 2024 年 7 月 24 日或之后，没有过期日期的现有个人访问令牌不会设置过期日期。

在 GitLab 自托管上，如果你安装以下 GitLab 版本之一，你的现有个人访问令牌不会自动应用过期日期：

• 16.0.9
• 16.1.7
• 16.2.10
• 16.3.8
• 16.4.6
• 16.5.9
• 16.6.9
• 16.7.9
• 16.8.9
• 16.9.10
• 16.10.9
• 16.11.7
• 17.0.5
• 17.1.3
• 17.2.1

个人访问令牌过期电子邮件

GitLab 每天在 1:00 AM UTC 运行检查，以识别即将在未来几天内过期的个人访问令牌。当这些令牌在特定天数内过期时，所有者会收到电子邮件通知。天数取决于 GitLab 版本：

• 在 GitLab 17.6 及更高版本中，当检查识别出个人访问令牌将在未来 60 天内过期时，个人访问令牌所有者会收到电子邮件通知。当检查识别出组访问令牌将在未来 30 天内过期时，会发送额外的电子邮件。
• 当检查识别出组访问令牌将在未来七天内过期时，个人访问令牌所有者会收到电子邮件通知。

个人访问令牌过期日历

你可以订阅一个 iCalendar 端点，其中包含每个令牌在过期日期的事件。登录后，此端点在 /-/user_settings/personal_access_tokens.ics 可用。

创建无过期日期的服务账户个人访问令牌

你可以 为服务账户创建无过期日期的个人访问令牌。这些个人访问令牌永远不会过期，与非服务账户的个人访问令牌不同。

GitLab.com

先决条件：

• 你必须拥有顶级组的所有者角色。

1. 在左侧边栏，选择 搜索或跳转 并找到你的组。
2. 选择 设置 > 常规 > 权限和组功能。
3. 清除 服务账户令牌过期 复选框。

你现在可以为服务账户用户创建无过期日期的个人访问令牌。

GitLab 自托管

先决条件：

• 你必须是你的 GitLab 自托管实例的管理员。

1. 在左侧边栏，底部，选择 管理。
2. 选择 设置 > 常规。
3. 展开 账户和限制。
4. 清除 服务账户令牌过期 复选框。

你现在可以为服务账户用户创建无过期日期的个人访问令牌。

使用 DPoP 与个人访问令牌

证明拥有权 (DPoP) 增强了你个人访问令牌的安全性，并最小化了意外令牌泄露的影响。当你为账户启用此功能时，所有包含 PAT 的 REST 和 GraphQL API 请求还必须提供签名的 DPoP 头。创建签名的 DPoP 头需要你相应的私钥。

GitLab CLI 生成 DPoP 头：

glab auth dpop-gen --pat "<your_access_token>" --private-key ~/.ssh/id_rsa

DPoP 头可用于：

• REST API：

curl --header "Private-Token: <your_access_token>" \
  --header "DPoP: <dpop-from-glab>" \
  "https://gitlab.example.com/api/v4/projects"

• GraphQL：

curl --request POST \
--header "Content-Type: application/json" \
--header "Private-Token: <your_access_token>" \
--header "DPoP: <dpop-from-glab>" \
--data '{
"query": "query { currentUser { id } }"
}' \
"https://gitlab.example.com/api/graphql"

要了解有关 DPoP 的更多信息，请参阅蓝图 发送者约束个人访问令牌。

以编程方式创建个人访问令牌

你可以创建预定义的个人访问令牌 作为测试或自动化的一部分。

先决条件：

• 你需要足够的权限来运行 Rails 控制台会话 用于你的 GitLab 实例。

要以编程方式创建个人访问令牌：

1. 打开 Rails 控制台：

sudo gitlab-rails console

1. 运行以下命令来引用用户名、令牌和权限范围。

令牌长度必须为 20 个字符。权限范围必须有效，并且可见于 源代码。

例如，创建一个属于用户名 automation-bot 且一年后过期的令牌：

user = User.find_by_username('automation-bot')
token = user.personal_access_tokens.create(scopes: ['read_user', 'read_repository'], name: 'Automation token', expires_at: 365.days.from_now)
token.set_token('token-string-here123')
token.save!

此代码可以通过使用 Rails runner 缩短为单行 shell 命令：

sudo gitlab-rails runner "token = User.find_by_username('automation-bot').personal_access_tokens.create(scopes: ['read_user', 'read_repository'], name: 'Automation token', expires_at: 365.days.from_now); token.set_token('token-string-here123'); token.save!"

以编程方式撤销个人访问令牌

你可以以编程方式撤销个人访问令牌 作为测试或自动化的一部分。

先决条件：

• 你需要足够的权限来运行 Rails 控制台会话 用于你的 GitLab 实例。

要以编程方式撤销令牌：

1. 打开 Rails 控制台：

sudo gitlab-rails console

1. 要撤销 token-string-here123 的令牌，运行以下命令：

token = PersonalAccessToken.find_by_token('token-string-here123')
token.revoke!

此代码可以通过使用 Rails runner 缩短为单行 shell 命令：

sudo gitlab-rails runner "PersonalAccessToken.find_by_token('token-string-here123').revoke!"

使用个人访问令牌克隆存储库

当 SSH 被禁用时，使用个人访问令牌克隆存储库，运行以下命令：

git clone https://<username>:<personal_token>@gitlab.com/gitlab-org/gitlab.git

此方法会将你的个人访问令牌保存在你的 bash 历史记录中。为避免这种情况，运行以下命令：

git clone https://<username>@gitlab.com/gitlab-org/gitlab.git

当被要求输入 https://gitlab.com 的密码时，输入你的个人访问令牌。

clone 命令中的 username：

• 可以是任何字符串值。
• 不能是空字符串。

如果你设置依赖于身份验证的自动化管道，请记住这一点。

故障排除

恢复个人访问令牌

如果个人访问令牌被任何方法意外撤销，管理员可以恢复该令牌。默认情况下，每日作业会在 1:00 AM 系统时间删除被撤销的令牌。

1. 打开 Rails 控制台。
2. 恢复令牌：

token = PersonalAccessToken.find_by_token('<token_string>')
token.update!(revoked:false)

例如，要恢复 token-string-here123 的令牌：

token = PersonalAccessToken.find_by_token('token-string-here123')
token.update!(revoked:false)

个人访问令牌的替代方案

对于 Git over HTTPS，个人访问令牌的替代方案是使用 OAuth 凭证助手。