グループアクセストークン

グループアクセストークンは、グループとそのプロジェクトへの認証されたアクセスを提供します。それらはパーソナルアクセストークンおよびプロジェクトアクセストークンに似ていますが、ユーザーやプロジェクトではなくグループに紐付けられています。グループアクセストークンを使用して、他のグループ、プロジェクト、またはパーソナルアクセストークンを作成することはできません。

グループアクセストークンを使用すると、次の認証が可能です。

• GitLab APIで認証。
• HTTPSを介したGitの場合。使用方法:
  • 任意の空白以外の値をユーザー名として使用します。
  • グループアクセストークンをパスワードとして使用します。

前提条件:

• グループのオーナーロール。

あなたのアクセストークンを表示する

グループアクセストークンページには、あなたのアクセストークンに関する情報が表示されます。

このページから、以下の操作を実行できます:

• グループアクセストークンの作成、ローテーション、および失効。
• すべてのアクティブなグループアクセストークンと無効なグループアクセストークンを表示します。
• トークン情報（スコープ、割り当てられたロール、有効期限を含む）を表示します。
• 使用状況の情報（使用日、および最後の5つの異なる接続IPアドレスを含む）を表示します。
  GitLabは、トークンがGit操作を実行したり、RESTまたはGraphQL APIで操作を認証したりすると、トークンの使用状況情報を定期的に更新します。トークンの使用時間は10分ごとに、トークン使用IPアドレスは1分ごとに更新されます。

あなたのグループアクセストークンを表示するには:

1. 上部のバーで、検索または移動先を選択して、グループを見つけます。
2. 設定 > アクセストークンを選択します。

アクティブで利用可能なアクセストークンは、アクティブなグループアクセストークンセクションに保存されます。期限切れ、ローテーション済み、または失効したトークンは、無効なグループアクセストークンセクションに保存されます。

グループアクセストークンの作成

UIを使用する場合

グループアクセストークンを作成するには:

1. 上部のバーで、検索または移動先を選択して、グループを見つけます。
2. 設定 > アクセストークンを選択します。
3. 新しいトークンを追加を選択します。
4. トークン名に、名前を入力します。トークン名は、グループを表示する権限を持つすべてのユーザーに表示されます。
5. オプション。トークンの説明に、トークンの説明を入力します。
6. 有効期限に、トークンの有効期限を入力します。
   • トークンは、その日のUTC深夜に期限が切れます。
   • 日付を入力しない場合、有効期限は今日から365日後に設定されます。
   • デフォルトでは、有効期限は今日から365日を超えることはできません。GitLab 17.6以降では、管理者はアクセストークンの最大ライフタイムを変更できます。
7. トークンのロールを選択します。
8. 1つまたは複数のグループアクセストークンのスコープを選択します。
9. グループアクセストークンを作成を選択します。

グループアクセストークンが表示されます。グループアクセストークンを安全な場所に保存します。ページを離れるか更新すると、再度表示することはできません。

すべてのグループアクセストークンは、パーソナルアクセストークンに設定されたデフォルトのプレフィックス設定を継承します。

Railsコンソールを使用する場合

管理者の場合は、Railsコンソールでグループアクセストークンを作成できます。

1. Railsコンソールで次のコマンドを実行します。

   # Set the GitLab administration user to use. If user ID 1 is not available or is not an administrator, use 'admin = User.admins.first' instead to select an administrator.
   admin = User.find(1)
   
   # Set the group you want to create a token for. For example, group with ID 109.
   group = Group.find(109)
   
   # Create the group bot user. For further group access tokens, the username should be `group_{group_id}_bot_{random_string}` and email address `group_{group_id}_bot_{random_string}@noreply.{Gitlab.config.gitlab.host}`.
   random_string = SecureRandom.hex(16)
   service_response = Users::CreateService.new(admin, { name: 'group_token', username: "group_#{group.id}_bot_#{random_string}", email: "group_#{group.id}_bot_#{random_string}@noreply.#{Gitlab.config.gitlab.host}", user_type: :project_bot }).execute
   bot = service_response.payload[:user] if service_response.success?
   
   # Confirm the group bot.
   bot.confirm
   
   # Add the bot to the group with the required role.
   group.add_member(bot, :maintainer)
   
   # Give the bot a personal access token.
   token = bot.personal_access_tokens.create(scopes:[:api, :write_repository], name: 'group_token')
   
   # Get the token value.
   gtoken = token.token

2. 生成されたグループアクセストークンが動作するかテストします。

   1. GitLab REST APIで、PRIVATE-TOKENヘッダーでグループアクセストークンを使用します。例:

      • グループにエピックを作成します。
      • グループのプロジェクトの1つにプロジェクトパイプラインを作成します。
      • グループのプロジェクトの1つにイシューを作成します。

   2. グループトークンを使用して、HTTPSを使ってグループのプロジェクトを複製します。

グループアクセストークンのスコープ

スコープは、グループアクセストークンで認証するときに利用可能なアクションを定義します。

グループアクセストークンをローテーションする

トークンをローテーションして、元のトークンと同じ権限とスコープを持つ新しいトークンを作成します。元のトークンは直ちに無効になり、GitLabは監査目的で両方のバージョンを保持します。アクセストークンページで、アクティブなトークンと無効なトークンの両方を表示できます。

GitLab Self-ManagedおよびGitLab Dedicatedでは、無効なトークンの保持期間を変更できます。

グループアクセストークンをローテーションするには:

1. 上部のバーで、検索または移動先を選択して、グループを見つけます。
2. 設定 > アクセストークンを選択します。
3. 関連するトークンのローテーション（ ）を選択します。
4. 確認ダイアログで、ローテーションを選択します。

グループアクセストークンを失効する

トークンを失効すると、直ちに無効になり、それ以降の使用が防止されます。トークンはすぐに削除されませんが、トークンリストをフィルタリングしてアクティブなトークンのみを表示できます。デフォルトでは、GitLabは失効したグループアクセストークンおよびプロジェクトアクセストークンを30日後に削除します。詳細については、無効なトークンの保持を参照してください。

グループアクセストークンを失効するには:

1. 上部のバーで、検索または移動先を選択して、グループを見つけます。
2. 設定 > アクセストークンを選択します。
3. 関連するトークンの取り消し（ ）を選択します。
4. 確認ダイアログで、取り消しを選択します。

アクセストークンの有効期限

パーソナルアクセストークン、グループアクセストークン、およびプロジェクトアクセストークンは、有効期限のUTC深夜に期限が切れます。期限切れになると、それらはリクエストを認証するために使用できなくなります。

GitLab 16.0以降では、新しいアクセストークンには有効期限が必要です。有効期限がトークン作成時に明示的に設定されていない場合、今日から365日間の有効期限が適用されます。Ultimateでは、管理者はアクセストークンの最大許容ライフタイムを設定できます。

あなたのGitLabバージョンと提供内容によっては、GitLabバージョンのアップグレード時に既存のアクセストークンに有効期限が自動的に適用される場合があります。詳細については、期限切れにならないアクセストークンを参照してください。

グループアクセストークンの有効期限に関するメール

GitLabは、まもなく期限切れになるグループアクセストークンを特定するために、UTC午前1:00に毎日チェックを実行します。オーナーロールを持つ直接のメンバーには、トークンの期限が切れる7日前にメールで通知されます。GitLab 17.6以降では、トークンの期限が切れる30日前と60日前にも通知が送信されます。

GitLab 17.7以降では、オーナーロールを持つ継承されたメンバーもこれらのメールを受け取ることができます。これは、GitLabインスタンス上のすべてのグループ、または特定のグループに対して設定できます。親グループに適用された場合、この設定はすべての子孫グループとプロジェクトに継承されます。

期限切れのトークンは、自動的に削除されるまで無効なグループアクセストークンセクションに表示されます。GitLab Self-Managedでは、この保持期間を変更できます。

グループのボットユーザー

グループアクセストークンを作成すると、GitLabはボットユーザーを作成し、それをトークンに関連付けます。

ボットユーザーは以下のプロパティを持っています:

• それらには、関連付けられたアクセストークンのロールとスコープに対応する権限が付与されます。
• それらはグループのメンバーであり、サブグループとプロジェクトのメンバーシップを継承しますが、他のグループやプロジェクトに直接追加することはできません。
• それらは非請求対象ユーザーであり、ライセンス制限にはカウントされません。
• 彼らのコントリビュートは、ボットユーザーアカウントに関連付けられています。
• 削除されると、彼らのコントリビュートはゴーストユーザーに移動されます。

ボットユーザーが作成されると、以下の属性が定義されます:

グループアクセストークンとプロジェクトアクセストークンの作成を制限する

潜在的な悪用を制限するために、トップレベルグループおよび任意の子孫サブグループやプロジェクトでのアクセストークンの作成をユーザーに制限できます。既存のトークンは、期限が切れるか手動で失効されるまで有効です。

アクセストークンの作成を制限するには:

1. 上部のバーで検索または移動先を選択し、トップレベルグループを見つけます。
2. 設定 > 一般を選択します。
3. 権限とグループ機能を展開します。
4. Users can create group access tokens and project access tokens in this groupチェックボックスをオフにします。
5. 変更を保存を選択します。

関連トピック

• パーソナルアクセストークン
• プロジェクトアクセストークン
• グループアクセストークンAPI