プロジェクトアクセストークン

プロジェクトアクセストークンはパスワードと似ていますが、リソースへのアクセスを制限したり、制限付きのロールを選択したり、有効期限を設定したりできます。

プロジェクトアクセストークンを使用して認証するには:

• GitLab APIを使用して認証します。
• Gitを使用します。HTTP基本認証を使う場合は次のようにします:
  • 任意の空白でない値をユーザー名として使用します。
  • パスワードとしてプロジェクトアクセストークンを使用します。

プロジェクトアクセストークンは、グループアクセストークンおよびパーソナルアクセストークンと似ていますが、関連付けられたプロジェクトにのみスコープが設定されています。プロジェクトアクセストークンを使用して、他のプロジェクトに属するリソースにアクセスすることはできません。

GitLab Self-Managedインスタンスでは、プロジェクトアクセストークンには、制限が設定されている場合、パーソナルアクセストークンと同じライフタイム制限が適用されます。

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

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

プロジェクトアクセストークンを作成する

プロジェクトアクセストークンを作成するには:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。
2. 設定 > アクセストークンを選択します。
3. 新しいトークンを追加を選択します。
4. トークン名に名前を入力します。トークン名は、プロジェクトを表示する権限を持つすべてのユーザーに表示されます。
5. オプション。トークンの説明に、トークンの説明を入力します。
6. 有効期限に、トークンの有効期限を入力します。
   • トークンは、その日付のUTC午前0時に期限切れになります。有効期限が2024-01-01のトークンは、2024-01-01の00:00:00 UTCに期限切れになります。
   • 有効期限を入力しない場合、有効期限は現在の日付より30日後に自動的に設定されます。
   • デフォルトでは、この日付は現在の日付より最大365日後に設定できます。GitLab 17.6以降では、この制限を400日に延長できます。
   • インスタンス全体のライフタイム設定により、GitLab Self-Managedインスタンスで許可される最大ライフタイムが制限される場合があります。
7. トークンのロールを選択します。
8. 必要なスコープを選択します。
9. Create project access token（プロジェクトアクセストークンを作成）を選択します。

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

プロジェクトアクセストークンを失効させる、またはローテーションする

GitLab 17.9以降、アクティブおよび非アクティブのプロジェクトアクセストークンの両方をアクセストークンページで表示できるようになります。

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

プロジェクトアクセストークンを失効させる、またはローテーションするには:

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

プロジェクトアクセストークンのスコープ

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

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

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

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

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

既存のプロジェクトアクセストークンに有効期限が自動的に適用されるかどうかは、お使いの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 176以降では、プロジェクトメンテナーおよびオーナーは、チェックによりプロジェクトアクセストークンが今後60日以内に期限切れになることが確認された場合に、メールで通知を受け取ります。プロジェクトアクセストークンが今後30日以内に期限切れになることが確認された場合、追加のメールを受け取ります。
• プロジェクトメンテナーおよびオーナーは、チェックによりプロジェクトアクセストークンが今後60日以内に期限切れになることが確認された場合に、メールで通知を受け取ります。
• GitLab 17.7以降では、プロジェクトがグループに属しているためにオーナーまたはメンテナーロールを継承したプロジェクトメンバーも、通知メールを受け取ることができます。これは、以下を変更することで有効にできます:
  • プロジェクトの親グループのいずれかのグループ設定。
  • GitLab Self-Managedでは、インスタンス設定。

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

プロジェクトのボットユーザー

プロジェクトのボットユーザーは、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コールは、対応するボットユーザーに関連付けられます。

プロジェクトのボットユーザー:

• プロジェクトのメンバーリストに含まれていますが、変更することはできません。
• 他のプロジェクトに追加することはできません。
• プロジェクトの最大ロールはオーナーにすることができます。詳細については、プロジェクトアクセストークンを作成するを参照してください。

プロジェクトアクセストークンが失効すると:

• 非アクティブなトークンの保持に準拠して、ボットユーザーが保持されます。
• 30日後、ボットユーザーは削除されます。すべてのレコードは、システム全体のユーザー名がGhostユーザーのユーザーに移動されます。

詳しくは、グループのボットユーザーをご覧ください。

非アクティブなトークンの保持

デフォルトでは、GitLabは、グループとプロジェクトアクセストークン、およびそれらのトークンファミリーを、トークンファミリーからの最後のアクティブなトークンが非アクティブになってから30日後に削除します。これにより、トークンファミリー内のすべてのトークンと、関連付けられたボットユーザーが削除され、ボットユーザーのコントリビューションがシステム全体の「Ghostユーザー」に移行されます。

非アクティブなトークンの保持期間を変更するには:

1. 左側のサイドバーの下部で、管理者を選択します。
2. 設定 > 一般を選択します。
3. アカウントと制限を展開します。
4. 非アクティブなプロジェクトやグループアクセストークンの保持期間テキストボックスで、保持期間を変更します。
   • 数値が定義されている場合、すべてのグループとプロジェクトアクセストークンは、指定された日数だけ非アクティブになった後に削除されます。
   • フィールドが空白の場合、非アクティブなトークンは削除されません。
5. 変更を保存を選択します。

アプリケーション設定APIを使用して、inactive_resource_access_tokens_delete_after_days属性を変更することもできます。

トークンの可用性

複数のプロジェクトアクセストークンは、有料のサブスクリプションでのみ利用可能です。PremiumとUltimateトライアルサブスクリプションの場合、含まれるプロジェクトアクセストークンは1つのみです。詳しくは、GitLabトライアルFAQの「何が含まれていますか」セクションをご覧ください。

関連トピック

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