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

グループアクセストークンを使用すると、単一のトークンで次の操作を実行できます:

• グループのアクションを実行する。
• グループ内のプロジェクトを管理する。

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

• GitLab APIで認証します。

• HTTPS経由のGitで認証。この場合、次のようにします:

  • 任意の空白以外の値をユーザー名として使用します。
  • グループアクセストークンをパスワードとして使用します。

グループアクセストークンはプロジェクトアクセストークンおよびパーソナルアクセストークンに似ていますが、プロジェクトまたはユーザーではなくグループに関連付けられている点が異なります。

グループアクセストークンを使用して、他のグループ、プロジェクト、またはパーソナルアクセストークンを作成することはできません。

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

可用性

• GitLab.comでは、PremiumまたはUltimateプランをお持ちの場合、グループアクセストークンを使用できます。トライアルライセンスでは使用できません。
• GitLab DedicatedおよびGitLab Self-Managedインスタンスのみ:
  • どのライセンス層でもグループアクセストークンを使用できます。Freeプランをお持ちの場合は、次のとおりです:
    • ユーザーのセルフ登録に関するセキュリティおよびコンプライアンス関連のポリシーを確認します。
    • 不正使用のリスクを軽減するために、グループアクセストークンの作成を制限することを検討してください。
  • GitLab Self-Managedインスタンスでは、制限が設定されている場合、グループアクセストークンはパーソナルアクセストークンと同じ最大ライフタイム制限の対象となります。

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

UIを使用する場合

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

1. 左側のサイドバーで、検索または移動先を選択して、グループを見つけます。
2. 設定 > アクセストークンを選択します。
3. 新しいトークンを追加を選択します。
4. トークン名に、名前を入力します。トークン名は、グループを表示する権限を持つすべてのユーザーに表示されます。
5. オプション。トークンの説明に、トークンの説明を入力します。
6. 有効期限に、トークンの有効期限を入力します:

   • トークンは、その日付のUTC午前0時に有効期限切れになります。有効期限が2024-01-01のトークンは、2024-01-01の00:00:00 UTCに期限切れになります。

   • 有効期限を入力しない場合、有効期限は現在の日付より365日後に自動的に設定されます。

   • デフォルトでは、この日付は現在の日付より最大365日後に設定できます。GitLab 17.6以降では、この制限を400日に延長できます。

   • インスタンス全体の最大ライフタイム設定により、GitLab Self-Managedインスタンスで許可される最大ライフタイムが制限される場合があります。

7. トークンのロールを選択します。
8. 必要なスコープを選択します。
9. Create group access token（グループアクセストークンを作成）を選択します。

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

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 17.9以降では、アクティブおよび非アクティブなグループアクセストークンをアクセストークンページで表示できます。

非アクティブなグループアクセストークンテーブルには、自動的に削除されるまで、失効および期限切れのトークンが表示されます。

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

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

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

スコープは、グループアクセストークンで認証するときに実行できるアクションを決定します。

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

潜在的な不正利用を制限するために、ユーザーがグループ階層のトークンを作成できないように制限できます。この設定は、トップレベルグループに対してのみ構成可能であり、すべてのダウンストリームサブグループおよびプロジェクトに適用されます。既存のグループアクセストークンは、有効期限が切れるまで、または手動で失効するまで有効なままです。

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

1. 左側のサイドバーで、検索または移動先を選択して、グループを見つけます。このグループはトップレベルにある必要があります。
2. 設定 > 一般を選択します。
3. 権限とグループ機能を展開します。
4. 権限で、Users can create project access tokens and group access tokens in this group（ユーザーはこのグループでプロジェクトアクセストークンとグループアクセストークンを作成できます）チェックボックスをオフにします。
5. 変更を保存を選択します。

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

既存のグループアクセストークンに有効期限が自動的に適用されるかどうかは、お使いのGitLabの提供形態と、GitLab 16.0以降にアップグレードした時期によって異なります:

• GitLab.comでは、16.0マイルストーン期間中に、有効期限のない既存のグループアクセストークンには、現在の日付より365日後の有効期限が自動的に付与されました。
• GitLab Self-Managedで、GitLab 15.11以前からGitLab 16.0以降にアップグレードした場合は、次のようになります:
  • 2024年7月23日以前は、有効期限のない既存のグループアクセストークンには、現在の日付より365日後の有効期限が自動的に付与されました。これは破壊的な変更です。
  • 2024年7月24日以降、有効期限のない既存のグループアクセストークンには有効期限が設定されませんでした。

GitLab Self-Managedで、次のいずれかの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は、UTC午前1時00分にチェックを毎日実行して、近い将来に有効期限が切れるグループアクセストークンを特定します。オーナーロールを持つグループのメンバーには、これらのトークンが特定の期間内に期限切れになるとメールで通知されます。日数はGitLabのバージョンによって異なります:

• GitLab 17.6以降では、チェックでグループアクセストークンが今後60日以内に期限切れになると識別された場合、グループオーナーはメールで通知されます。チェックでグループアクセストークンが今後30日以内に期限切れになると識別された場合、追加のメールが送信されます。
• チェックでグループアクセストークンが今後7日以内に期限切れになると識別された場合に、グループオーナーはメールで通知されます。
• GitLab 17.7以降では、グループ内でオーナーロールを継承したメンバーも通知メールを受信できます。これは、以下を変更することで設定できます:
  • グループまたは親グループのグループ設定。
  • GitLab Self-Managedでは、インスタンス設定。

期限切れのアクセストークンは、自動的に削除されるまで、非アクティブなグループアクセストークンテーブルにリストされます。

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

グループのボットユーザーは、GitLabが作成した請求対象外のユーザーです。グループアクセストークンを作成するたびに、ボットユーザーが作成され、グループに追加されます。これらのボットユーザーはプロジェクトのボットユーザーに似ていますが、プロジェクトではなくグループに追加される点が異なります。グループのボットユーザーは、次のようなユーザーです:

• 請求対象ユーザーではないため、ライセンス制限にはカウントされません。
• グループの最大ロールはオーナーにすることができます。詳しくは、グループアクセストークンの作成をご覧ください。
• ユーザー名はgroup_{group_id}_bot_{random_string}に設定されています。たとえば、group_123_bot_4ffca233d8298ea1のようにします。
• メールはgroup_{group_id}_bot_{random_string}@noreply.{Gitlab.config.gitlab.host}に設定されています。たとえば、group_123_bot_4ffca233d8298ea1@noreply.example.comのようにします。

その他すべてのプロパティは、プロジェクトのボットユーザーと同様です。

トークンの可用性

グループアクセストークンは、有料サブスクリプションでのみ利用可能で、トライアルサブスクリプションでは利用できません。詳しくは、GitLabトライアルFAQの「何が含まれていますか」セクションをご覧ください。

関連トピック

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