如何創建并使用極狐GitLab 項目訪問令牌？

極狐GitLab 是 GitLab 在中國的發行版，關于中文參考文檔和資料有：

極狐GitLab 中文文檔
極狐GitLab 中文論壇
極狐GitLab 官網

項目訪問令牌

在極狐GitLab 16.1中引入添加了默認前綴。

項目訪問令牌類似于密碼，但你可以限制訪問資源，選擇有限的角色，并提供到期日期。

注意：對項目的實際訪問是由角色和權限和令牌作用域的組合控制的。

使用項目訪問令牌進行身份驗證：

使用GitLab API。
使用Git時，使用HTTP基本認證：
- 任何非空值作為用戶名。
- 將項目訪問令牌作為密碼。

項目訪問令牌類似于組訪問令牌和個人訪問令牌，但項目訪問令牌僅限于一個項目，因此無法用于訪問其他項目的資源。

在自管理實例中，如果設置了限制，項目訪問令牌與個人訪問令牌一樣，受相同的最大生命周期限制。

你可以在以下環境中使用項目訪問令牌：

在極狐SaaS上：如果你擁有Premium或Ultimate許可證層次，試用許可證中只能使用一個項目訪問令牌試用許可證。
在極狐GitLab自管理實例中：適用于任何許可證層次。如果你使用的是 Free 層級，可以考慮限制創建項目訪問令牌，以降低潛在的濫用風險。

你無法使用項目訪問令牌創建其他組、項目或個人訪問令牌。

項目訪問令牌繼承了為個人訪問令牌配置的默認前綴設置。

創建項目訪問令牌

在極狐GitLab 15.1中引入所有者可以為項目訪問令牌選擇所有者角色。
在極狐GitLab 15.3中引入UI中預設了30天的默認過期時間和默認的訪客角色。
在極狐GitLab 16.0中移除創建無過期日期的項目訪問令牌的能力。
在極狐GitLab 17.6中引入最大可允許的生命周期限制擴展到400天，并帶有名為 buffered_token_expiration_limit 的功能標志，默認禁用。

WARNING:在極狐GitLab 15.4中，創建沒有過期日期的項目訪問令牌的能力已被棄用，并且在極狐GitLab 16.0中已被移除。有關已添加過期日期的現有令牌的更多信息，請參見訪問令牌過期。

要創建項目訪問令牌：

1.在左側邊欄中，選擇 搜索或轉到 并找到你的項目。
2.選擇 設置 > 訪問令牌。
3.選擇 添加新令牌。
4.在 令牌名稱 中，輸入一個名稱。令牌名稱對所有具有查看項目權限的用戶可見。
5.可選。在 令牌描述 中，輸入令牌的描述。
6.在 過期日期 中，輸入令牌的過期日期。

令牌將在該日期的 UTC 時間午夜過期。比如，2024-01-01的過期日期將在2024-01-01 00:00:00UTC 過期。
如果沒有輸入過期日期，過期日期會自動設置為當前日期的30天后。
默認情況下，日期的最大值可以是當前日期的365天后。在極狐GitLab 17.6或更高版本中，你可以擴展此限制至400天。
實例范圍的最大生命周期設置可以限制自托管實例中允許的最大生命周期。

7.為令牌選擇一個角色。
8.選擇所需的作用域。
9.選擇 創建項目訪問令牌。

項目訪問令牌將顯示。請將項目訪問令牌保存在安全的地方。離開頁面或刷新頁面后，無法再次查看該令牌。

WARNING:項目訪問令牌被視為內部用戶。如果內部用戶創建了項目訪問令牌，則該令牌能夠訪問所有設置為內部可見性級別的項目。

撤銷或輪換項目訪問令牌

在極狐GitLab 17.3中引入查看已撤銷令牌的功能，帶有一個標志名為retain_resource_access_token_user_after_revoke，默認禁用。

在極狐GitLab 17.3及更高版本中，如果啟用retain_resource_access_token_user_after_revoke 功能標志，你可以在訪問令牌頁面上查看活動和非活動的已撤銷項目訪問令牌。如果未啟用該功能標志，你只能查看活動令牌。非活動項目訪問令牌表格：

包含：
- 已撤銷但尚未過期的現有令牌。此類令牌在過期后將不再顯示在表格中。
- 在啟用功能標志后創建的并且已被撤銷的令牌。這些令牌即使過期后仍將顯示在表格中。
不包含：
- 已經過期或已被撤銷的令牌。
- 將來會過期或尚未被撤銷的現有令牌。

使用UI

要撤銷或輪換項目訪問令牌：

1.在左側邊欄中，選擇 搜索或轉到 并找到你的項目。
2.選擇 設置 > 訪問令牌。
3.對于相關令牌，選擇 撤銷 ({remove}) 或 輪換 ({retry})。
4,在確認對話框中，選擇撤銷或輪換。

項目訪問令牌的作用域

在極狐GitLab 16.4中引入k8s_proxy，帶有一個標志名為k8s_proxy_pat，默認啟用。
在極狐GitLab 16.5中移除k8s_proxy_pat功能標志。

作用域決定了當你使用項目訪問令牌進行身份驗證時可以執行的操作。

NOTE:請參見創建項目訪問令牌中關于內部項目的警告。

作用域	描述
`api`	授予對作用域項目API的完全讀寫訪問權限，包括容器注冊表、依賴代理和包注冊表。
`read_api`	授予對作用域項目API的讀取訪問權限，包括包注冊表。
`read_registry`	授予對容器注冊表鏡像的讀取訪問權限（拉取），如果項目是私有的并且需要授權。
`write_registry`	授予對容器注冊表的寫入訪問權限（推送）。推送鏡像需要同時擁有讀取和寫入權限。
`read_repository`	授予對倉庫的讀取訪問權限（拉取）。
`write_repository`	授予對倉庫的讀寫訪問權限（拉取和推送）。
`create_runner`	授予在項目中創建運行器的權限。
`manage_runner`	授予管理項目中運行器的權限。
`ai_features`	授予對GitLab Duo執行API操作的權限。此作用域設計為與JetBrains的 GitLab Duo 插件一起使用。對于所有其他擴展，請參閱作用域要求。
`k8s_proxy`	授予使用Kubernetes代理在項目中執行Kubernetes API調用的權限。

限制創建項目訪問令牌

為減少濫用風險，你可以限制用戶在組層次結構中創建令牌。此設置僅對頂級組可配置，并適用于每個下游項目和子組。任何現有的項目訪問令牌在其過期日期或手動撤銷之前仍然有效。

1.在左側邊欄中，選擇 搜索或轉到 并找到你的組。
2.該組必須是頂級組。
3.選擇 設置 > 常規。
4.展開 權限和組功能。
5.在權限部分，清除用戶可以在該組中創建項目訪問令牌和組訪問令牌 復選框。

訪問令牌過期

是否自動為現有的項目訪問令牌應用過期日期，取決于你所使用的極狐GitLab 版本以及你何時升級到極狐GitLab 16.0或更高版本：

在極狐saas上，在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 17.6中引入六十天和三十天過期通知郵件，帶有一個標志名為 expiring_pats_30d_60d_notifications，默認禁用。

極狐GitLab每天1:00 AM UTC進行一次檢查，以識別即將過期的項目訪問令牌。當檢查識別出項目訪問令牌將在接下來的特定天數內過期時，至少擁有維護者角色的項目成員會通過郵件通知他們的令牌過期。不同版本的極狐GitLab有不同的通知規則：

在極狐GitLab 17.6及更高版本中，項目的維護者和所有者將在令牌將在接下來的60天內過期時通過郵件通知。檢查發現令牌將在接下來的30天內過期時，還會發送另一封郵件通知。
項目的維護者和所有者將在令牌將在接下來的7天內過期時通過郵件通知。

項目機器人的用戶

在極狐GitLab 17.2中更改帶有一個標志名為 retain_resource_access_token_user_after_revoke，默認禁用。啟用后，新的機器人用戶沒有。

項目機器人的用戶是GitLab 創建的非計費用戶。
每次創建項目訪問令牌時，都會創建一個機器人用戶并將其添加到項目中。

該用戶不是計費用戶，因此不計入許可證限制。

項目機器人的用戶具有與項目訪問令牌所選角色和作用域相對應的權限。

名稱設置為令牌的名稱。
用戶名設置為project_{project_id}_bot_{random_string}，例如project_123_bot_4ffca233d8298ea1。
電子郵件設置為project_{project_id}_bot_{random_string}@noreply.{Gitlab.config.gitlab.host}，例如project_123_bot_4ffca233d8298ea1@noreply.example.com。

使用項目訪問令牌進行的API調用將與相應的機器人用戶關聯。
項目機器人的用戶：