正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。
ドキュメントに関する現在のご利用体験についてお聞かせください。アンケートにご協力ください。

パーソナルアクセストークン

  • プラン: Free、Premium、Ultimate
  • 提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

パーソナルアクセストークンは、GitLabへの認証済みアクセストークンを提供します。これらはOAuth2トークンの代替であり、グループアクセストークンおよびプロジェクトアクセストークンと似ていますが、グループまたはプロジェクトではなくユーザーに紐付けられます。

パーソナルアクセストークンを使用して、以下を認証することができます:

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

2要素認証またはSAMLが有効になっている場合は、パーソナルアクセストークンで認証する必要があります。

GitLabマネージドTerraformステートバックエンドやコンテナレジストリなど、ユーザー名を必要とする一部のGitLab機能では、GitLabユーザー名とパーソナルアクセストークンを使用します。これらのケースでは、ユーザー名は必須ですが、認証の一部として評価されません。詳細については、イシュー212953を参照してください。

GitLab Self-ManagedおよびGitLab Dedicatedインスタンスでは、管理者はユーザートークンAPIを使用して、特定のユーザーとして認証するための代理トークンを作成できます。

パーソナルアクセストークンを作成する

延長された最大許容ライフタイム制限の利用可否は、機能フラグによって制御されます。詳細については、履歴を参照してください。

パーソナルアクセストークンを作成するには:

  1. 右上隅で、アバターを選択します。
  2. プロファイルを編集を選択します。
  3. 左サイドバーで、アクセス > パーソナルアクセストークンを選択します。
  4. トークンを生成ドロップダウンリストから、レガシートークンを選択します。
  5. トークン名に、トークンの名前を入力します。
  6. オプション。トークンの説明に、トークンの説明を入力します。
  7. 有効期限に、トークンの有効期限を入力します。
    • トークンは、その日のUTC深夜に期限が切れます。
    • 日付を入力しない場合、有効期限は今日から365日後に設定されます。
    • デフォルトでは、有効期限は今日から365日を超えることはできません。GitLab 17.6以降では、管理者はアクセストークンの最大ライフタイムを変更できます。
  8. 1つまたは複数のパーソナルアクセストークンのスコープを選択します。
  9. トークンを生成を選択します。

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

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

パーソナルアクセストークンの詳細を事前に入力する

名前、説明、およびスコープのリストをURLに付加することで、パーソナルアクセストークンの詳細を事前に入力できます。例:

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

パーソナルアクセストークンは慎重に取り扱う必要があります。パーソナルアクセストークンの管理に関するガイダンスについては、トークンのセキュリティに関する考慮事項を参照してください。

アクセストークンで認証する

アクセストークンを使用して、GitLab REST API、HTTPS経由のGit、およびGitLabと統合するサードパーティツールで認証します。

REST APIを使用する

あなたのトークンをPRIVATE-TOKENヘッダーに渡します:

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects"

詳細については、REST API認証を参照してください。

HTTPS経由でGitを使用する

Gitが認証情報を要求したときに、あなたのトークンをパスワードとして使用します:

  • ユーザー名: 空でない任意の文字列（GitLabはこの値を検証しません）。
  • パスワード: あなたのパーソナルアクセストークン。

例:

shell
git clone https://oauth2:<your_access_token>@gitlab.example.com/gitlab-org/gitlab.git

サードパーティツールとIDE拡張機能を使用する

GitLabと統合するIDE拡張機能、CI/CDツール、自動化スクリプトなどのツールは、認証のためにパーソナルアクセストークンを受け入れます。各ツールに関するドキュメントを参照してください:

CI/CDパイプラインには、代わりにCI/CDジョブトークンが推奨されます。

パーソナルアクセストークンのセキュリティガイダンスについては、トークンのセキュリティに関する考慮事項を参照してください。

トークンの使用状況情報を表示する

パーソナルアクセストークンページには、アクセストークンに関する情報が表示されます。

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

  • パーソナルアクセストークンの作成、ローテーション、および失効。
  • アクティブおよび非アクティブなすべてのパーソナルアクセストークンを表示します。
  • トークン情報（スコープ、割り当てられたロール、有効期限を含む）を表示します。
  • 使用状況の情報（使用日、および最後の5つの異なる接続IPアドレスを含む）を表示します。

    GitLabは、トークンがGit操作を実行したり、RESTまたはGraphQL APIで操作を認証するときに、トークンの使用状況情報を定期的に更新します。トークンの使用時間は10分ごとに、トークン使用IPアドレスは1分ごとに更新されます。

パーソナルアクセストークンを表示するには:

  1. 右上隅で、アバターを選択します。
  2. プロファイルを編集を選択します。
  3. 左サイドバーで、アクセス > パーソナルアクセストークンを選択します。

詳細パネルを開くには、トークンの名前を選択します。デフォルトでは、アクティブなトークンのみが表示されます。検索バーを使用して、アクセストークンのリストをフィルタリングします。

パーソナルアクセストークンをローテーションする

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

この操作は元に戻せません。ローテーションされたアクセストークンに依存するツールは、新しいトークンを参照するまで機能しなくなります。

パーソナルアクセストークンをローテーションするには:

  1. 右上隅で、アバターを選択します。
  2. プロファイルを編集を選択します。
  3. 左サイドバーで、アクセス > パーソナルアクセストークンを選択します。
  4. アクティブなトークンの横にある縦方向の省略記号（ ellipsis_v ）を選択します。
  5. ローテーション（ retry ）を選択します。
  6. 確認ダイアログで、ローテーションを選択します。

パーソナルアクセストークンを失効させる

トークンを失効すると、直ちに無効になり、それ以降の使用が防止されます。GitLabは監査目的でトークンを保持します。トークンを完全に削除することはできませんが、トークンリストをフィルタリングしてアクティブなトークンのみを表示できます。

この操作は元に戻せません。失効したアクセストークンに依存するツールは、新しいトークンを追加するまで機能しなくなります。

パーソナルアクセストークンを失効するには:

  1. 右上隅で、アバターを選択します。
  2. プロファイルを編集を選択します。
  3. 左サイドバーで、アクセス > パーソナルアクセストークンを選択します。
  4. アクティブなトークンの横にある縦方向の省略記号（ ellipsis_v ）を選択します。
  5. 取り消し（ remove ）を選択します。
  6. 確認ダイアログで、取り消しを選択します。

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

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

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

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

パーソナルアクセストークンの有効期限に関するメール

GitLabは、まもなく有効期限が切れるパーソナルアクセストークンを特定するために、毎日UTC午前1:00にチェックを実行します。トークンの有効期限が切れる7日前に、ユーザーにメールで通知されます。GitLab 17.6以降では、トークンの期限が切れる30日前と60日前にも通知が送信されます。

パーソナルアクセストークンの有効期限カレンダー

各トークンの有効期限にイベントが設定されたiCalendarエンドポイントをサブスクライブできます。サインイン後、このエンドポイントは/-/user_settings/personal_access_tokens.icsで利用できます。

有効期限のないサービスアカウントのパーソナルアクセストークンを作成する

有効期限のないサービスアカウントのパーソナルアクセストークンを作成できます。これらのパーソナルアクセストークンは、通常のアカウントのパーソナルアクセストークンとは異なり、有効期限切れになることはありません。

有効期限なしでサービスアカウント用のパーソナルアクセストークンを作成できるようにすることは、この設定を変更した後に作成されたトークンにのみ影響します。既存のトークンには影響しません。

GitLab.com

前提条件:

  • トップレベルグループのオーナーロールが必要です。
  1. 上部のバーで、検索または移動先を選択して、グループを見つけます。
  2. 左側のサイドバーで、設定 > 一般を選択します。
  3. 権限とグループ機能を展開します。
  4. パーソナルアクセストークンの下で、サービスアカウントに有効期限を設定するチェックボックスをオフにします。

これで、有効期限のないサービスアカウントユーザーのパーソナルアクセストークンを作成できます。

GitLab Self-Managed

前提条件:

  • GitLab Self-Managedインスタンスの管理者である必要があります。
  1. 右上隅で、管理者を選択します。
  2. 左側のサイドバーで、設定 > 一般を選択します。
  3. アカウントと制限を展開します。
  4. サービスアカウントトークンの有効期限チェックボックスをオフにします。

これで、有効期限のないサービスアカウントユーザーのパーソナルアクセストークンを作成できます。

パーソナルアクセストークンを使用してリポジトリをクローンする

SSHが無効になっている場合にリポジトリをクローンするには、次のコマンドを実行してパーソナルアクセストークンを使用してクローンします。

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

この方法では、パーソナルアクセストークンがbashの履歴に保存されます。これを回避するには、次のコマンドを実行します。

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

https://gitlab.comのパスワードを求められたら、パーソナルアクセストークンを入力します。

cloneコマンドのusernameは、次の条件を満たす必要があります。

  • 任意の文字列を指定できます。
  • 空の文字列は使用できません。

認証に依存する自動化パイプラインを設定する場合は、この条件を必ず守ってください。

アクセストークンを無効にする

  • プラン: Premium、Ultimate
  • 提供形態: GitLab Self-Managed、GitLab Dedicated

前提条件:

  • 管理者アクセス権。

GitLabインスタンス全体で、ユーザーがアクセストークンで認証するのを防ぐことができます。この設定は、パーソナルアクセストークン、グループアクセストークン、プロジェクトアクセストークン、および代理トークンに影響します。この設定は、サービスアカウントのパーソナルアクセストークンにも適用されます。

アクセストークンを無効にすると、次のルールが適用されます:

  • ユーザーはパーソナルアクセストークンを使用してGitLabにサインインできません。
  • パーソナルアクセストークンページは、404 Not Foundエラーを返します。
  • RSS、Atom、およびカレンダーフィードのフィードトークンは機能しなくなります。
  • パーソナルアクセストークンで認証されたAPIリクエストは拒否されます。

インスタンスのアクセストークンを無効にするには:

  1. 右上隅で、管理者を選択します。
  2. 左側のサイドバーで、設定 > 一般を選択します。
  3. アカウントと制限を展開します。
  4. アクセストークンを無効にするチェックボックスを選択します。
  5. 変更を保存を選択します。

アプリケーション設定APIでdisable_personal_access_tokens属性を使用することもできます。

エンタープライズユーザーのパーソナルアクセストークンを無効にする

  • プラン: Premium、Ultimate
  • 提供形態: GitLab.com

前提条件:

  • エンタープライズユーザーが所属するグループのオーナーロール。

グループのエンタープライズユーザーのパーソナルアクセストークンを無効にすると、次のようになります。

  • エンタープライズユーザーは新しいパーソナルアクセストークンを作成できなくなります。この動作は、エンタープライズユーザーがグループ管理者である場合でも適用されます。
  • エンタープライズユーザーの既存のパーソナルアクセストークンが無効になります。

エンタープライズユーザーのパーソナルアクセストークンを無効にしても、サービスアカウントのパーソナルアクセストークンは無効になりません。

エンタープライズユーザーのパーソナルアクセストークンは、次の手順で無効にできます。

  1. 上部のバーで、検索または移動先を選択して、グループを見つけます。
  2. 左側のサイドバーで、設定 > 一般を選択します。
  3. 権限とグループ機能を展開します。
  4. エンタープライズのユーザーで、パーソナルアクセストークンを無効にするを選択します。
  5. 変更を保存を選択します。

エンタープライズユーザーアカウントを削除またはブロックすると、そのユーザーのパーソナルアクセストークンは自動的に取り消されます。

プログラムを利用してパーソナルアクセストークンを作成する

  • 提供形態: GitLab Self-Managed、GitLab Dedicated

テストまたは自動化の一環として、事前に決定されたパーソナルアクセストークンを作成できます。

前提条件:

プログラムを利用してパーソナルアクセストークンを作成する手順は次のとおりです。

  1. Railsコンソールを開きます。

    shell
    sudo gitlab-rails console

  2. 次のコマンドを実行して、ユーザー名、トークン、スコープを参照します。

    トークンは20文字の長さでなければなりません。スコープは有効である必要があり、ソースコードで表示できます。

    たとえば、ユーザー名がautomation-botのユーザーに属し、1年後に期限切れになるトークンは、次のコマンドで作成できます。

    ruby
    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!"

プログラムを利用してパーソナルアクセストークンを取り消す

  • 提供形態: GitLab Self-Managed、GitLab Dedicated

テストまたは自動化の一環として、プログラムを利用してパーソナルアクセストークンを取り消すことができます。

前提条件:

プログラムを利用してトークンを取り消す手順は次のとおりです。

  1. Railsコンソールを開きます。

    shell
    sudo gitlab-rails console

  2. 次のコマンドを実行して、token-string-here123のトークンを取り消します。

    ruby
    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!"

パーソナルアクセストークンでDPoPを使用する

  • 提供形態: GitLab.com、GitLab Self-Managed

この機能の利用可否は、機能フラグによって制御されます。詳細については、履歴を参照してください。この機能はテストには利用できますが、本番環境での使用には適していません。

Demonstrating Proof of Possession（DPoP、所有証明の実証）は、パーソナルアクセストークンのセキュリティを強化し、意図しないトークンの漏洩の影響を最小限に抑えます。アカウントでこの機能を有効にすると、PATを含むすべてのRESTおよびGraphQL APIリクエストで、署名付きDPoPヘッダーも提供する必要が生じます。署名付きDPoPヘッダーを作成するには、対応する秘密SSHキーが必要です。

この機能を有効にすると、有効なDPoPヘッダーを持たないすべてのAPIリクエストはDpopValidationErrorエラーを返します。

アクセストークンを含むHTTPS経由のGitオペレーションでは、DPoPヘッダーは必須ではありません。

前提条件:

RESTおよびGraphQL APIへのすべての呼び出しで、DPoPを要求するには:

  1. 右上隅で、アバターを選択します。

  2. プロファイルを編集を選択します。

  3. 左サイドバーで、アクセス > パーソナルアクセストークンを選択します。

  4. Demonstrating Proof of Possession（DPoP）の使用セクションに移動し、DPoPを有効にするを選択します。

  5. 変更を保存を選択します。

  6. ターミナルで次のコマンドを実行して、GitLab CLIでDPoPヘッダーを生成します。<your_access_token>をアクセストークンに、~/.ssh/id_rsaを秘密キーの場所に置き換えます。

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

CLIで生成したDPoPヘッダーは、以下のように使用できます。

  • REST APIでの使用:

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

  • GraphQLでの使用:

    shell
     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の詳細については、ブループリント送信者制約パーソナルアクセストークンを参照してください。

パーソナルアクセストークンの代替

HTTPS経由のGitの場合、パーソナルアクセストークンの代替として、OAuth認証ヘルパーを使用できます。

CI/CDジョブでの認証には、以下を考慮してください: