個人アクセストークン

  • GitLab 12.6で導入されたトークンの期限切れ通知。
  • GitLab 12.6 で導入されたトークンのライフタイム制限。
  • GitLab 13.3 で導入された、期限切れトークンの追加通知。
  • GitLab 14.1 で導入されたトークン名とスコープのプレフィル。

パーソナルアクセストークンはOAuth2の代替となり、以下のような用途に使用できます:

どちらの場合も、パスワードの代わりに個人用のアクセストークンを使って認証します。

caution
有効期限のない個人アクセストークンを作成する機能は、GitLab 15.4で非推奨となり、GitLab 16.0で削除されました。GitLab 16.0以降では、有効期限のない既存の個人アクセストークンには、現在の日付より365日後の有効期限が自動的に付与されます。有効期限の自動追加は、16.0のマイルストーン中にGitLab.com上で行われます。有効期限の自動追加は、セルフマネージドインスタンスがGitLab 16.0にアップグレードされたときに発生します。この変更はブレークチェンジです。

個人アクセストークンは以下の通りです:

note
必須ではありますが、個人アクセストークンで認証する場合、GitLabのユーザー名は無視されます。GitLab にユーザー名を使わせるためのトラッキングのイシューがあります。

個人アクセストークンを使った API 認証の例については、API ドキュメントをご覧ください。

別の方法として、GitLab 管理者は API を使ってなりすましトークンを作成することができます。なりすましトークンを使って、特定のユーザーとしての認証を自動化しましょう。

個人アクセストークンの作成

  • GitLab 15.3で導入され、デフォルトの有効期限は30日です。
  • GitLab 16.0で、有効期限がない個人アクセストークンを作成する機能が削除されました。

個人アクセストークンはいくつでも作成できます。

  1. 左のサイドバーで、自分のアバターを選択してください。
  2. プロフィールの編集を選択します。
  3. 左サイドバーで、アクセストークンを選択します。
  4. 新しいトークンを追加]を選択します。
  5. トークンの名前と有効期限を入力します。
    • トークンの有効期限はその日の午前0時(UTC)です。
    • 有効期限を入力しない場合、有効期限は自動的に現在の日付より365日後に設定されます。
    • デフォルトでは、この日付は現在の日付より最大 365 日遅くなります。
  6. 必要なスコープを選択します。
  7. 個人アクセストークンの作成」を選択します。

個人アクセストークンを安全な場所に保存します。ページを閉じると、アクセストークンにアクセスできなくなります。

個人アクセストークン名とスコープを事前に入力してください。

個人アクセストークンのページに直接リンクし、フォームに名前とスコープのリストをプリフィルすることができます。これを行うには、name パラメータとカンマで区切られたスコープのリストを URL に追加します。例えば

https://gitlab.example.com/-/profile/personal_access_tokens?name=Example+Access+token&scopes=api,read_user,read_registry
caution
個人アクセストークンの扱いには注意が必要です。個人アクセストークンを管理するためのガイダンス (たとえば、有効期限を短く設定する、最小限のスコープを使うなど) については、トークンのセキュリティに関する考慮事項をお読みください。

個人アクセストークンの取り消し

アクセストークンはいつでも失効させることができます。

  1. 左のサイドバーで、自分のアバターを選択してください。
  2. プロフィールの編集を選択します。
  3. 左サイドバーで、アクセストークンを選択します。
  4. アクティブな個人アクセストークン] 領域で、キーの横にある [失効] を選択します。

トークンが最後に使用された時刻の表示

  • GitLab 13.2 で導入されました。トークンの使用情報は24時間ごとに更新されます。
  • GitLab 16.1でトークン使用情報の更新頻度が24時間から10分に変更されました。

トークンの使用情報は10分ごとに更新されます。GitLabはトークンが使用されると、トークンが使用されたとみなします:

  • RESTまたはGraphQLAPI での認証。
  • Git オペレーションを実行します。

トークンが最後に使われた時刻を見るには

  1. 左のサイドバーで、自分のアバターを選択してください。
  2. プロフィールの編集を選択します。
  3. 左サイドバーで、アクセストークンを選択します。
  4. アクティブな個人アクセストークン]エリアのキーの横にある[最終使用日]を表示します。

個人アクセストークンのスコープ

GitLab 16.0で導入されたコンテナやパッケージのレジストリにアクセスできなくなった個人アクセストークン。

パーソナルアクセストークンは、割り当てられたスコープに基づいてアクションを実行することができます。

スコープアクセス
apiすべてのグループとプロジェクト、コンテナレジストリ、パッケージレジストリを含む API への完全な読み取り/書き込みアクセスを許可します。
read_user /user API エンドポイントを介した、認証済みユーザーのプロファイル(ユーザー名、公開電子メール、フルネーム)への読み取り専用アクセスを付与します。また、/users以下の読み取り専用 API エンドポイントへのアクセスも許可します。
read_apiすべてのグループとプロジェクト、コンテナレジストリ、パッケージレジストリを含む API への読み取りアクセスを許可します。(GitLab 12.10 で導入)。
read_repositoryGit-over-HTTP あるいは Repository Files API を使って非公開プロジェクトのリポジトリへの読み込み専用アクセスを許可します。
write_repositoryGit-over-HTTP を使用する非公開プロジェクトのリポジトリへの読み書きアクセスを許可します (API は使用しません)。
read_registryプロジェクトが非公開で作成者の認証が必要な場合に、コンテナレジストリ画像への読み込み専用 (pull) アクセスを許可します。コンテナレジストリが有効な場合にのみ有効です。
write_registryプロジェクトが非公開で作成者の認証が必要な場合に、コンテナレジストリのイメージへの読み書き(プッシュ)アクセスを許可します。コンテナレジストリが有効な場合のみ利用可能です。(GitLab 12.10 で導入)。
sudo管理者として認証された場合に、システム内のどのユーザーとしても API アクションを実行する権限を付与します。
admin_mode管理者モードが有効な場合、管理者としてAPIアクションを実行する権限を付与します。(GitLab 15.8で導入)。
create_runnerRunnerの作成権限を付与します。
caution
外部認証を有効にすると、個人アクセストークンはコンテナまたはパッケージのレジストリにアクセスできなくなります。個人アクセストークンを使用してこれらのレジストリにアクセスする場合、このメジャーによってこれらのトークンの使用が制限されます。コンテナまたはパッケージ・レジストリで個人アクセストークンを使用するには、外部認証を無効にします。

個人アクセストークンの有効期限が切れた場合

個人アクセストークンの有効期限は、お客様が定義された日付の午前0時(UTC)です。

  • GitLabは毎日UTC午前01:00にチェックを行い、7日以内に有効期限が切れるパーソナルアクセストークンを特定します。これらのトークンのオーナーにはメールで通知されます。
  • GitLabは毎日02:00 AM UTCにチェックを実行し、現在の日付で期限が切れる個人アクセストークンを特定します。これらのトークンのオーナーにはメールで通知されます。
  • GitLab Ultimateでは、管理者はアクセストークンの有効期限を制限することができます。設定されていない場合、個人アクセストークンの最大有効期限は365日です。
  • GitLab FreeとPremiumでは、個人アクセストークンの最大有効期間は365日です。

プログラムによるパーソナルアクセストークンの作成

テストや自動化の一環として、所定のパーソナルアクセストークンを作成することができます。

前提条件

個人アクセストークンをプログラムで作成するには

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

    sudo gitlab-rails console
    
  2. 以下のコマンドを実行して、ユーザ名、トークン、スコープを参照します。

    トークンは20文字でなければなりません。スコープは有効で、ソースコードから見えるものでなければなりません。

    例えば、ユーザー名automation-bot のユーザーに属するトークンを作成し、有効期限を 1 年とします:

    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を使うことで1行のシェルコマンドに短縮できます:

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

個人アクセストークンをプログラムで取り消す

テストや自動化の一環として、個人アクセストークンをプログラムで失効させることができます。

前提条件

トークンをプログラムで失効させるには

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

    sudo gitlab-rails console
    
  2. token-string-here123 のトークンを取り消すには、以下のコマンドを実行します:

    token = PersonalAccessToken.find_by_token('token-string-here123')
    token.revoke!
    

このコードは、Rails Runnerを使用して1行のシェルコマンドに短縮できます:

sudo gitlab-rails runner "PersonalAccessToken.find_by_token('token-string-here123').revoke!"

個人アクセストークンを使ったリポジトリのクローン

SSH が無効になっているときにリポジトリをクローンするには、次のコマンドを実行して個人アクセストークンを使用してリポジトリをクローンします:

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

この方法では、個人アクセストークンが Bash 履歴に保存されます。これを避けるには、次のコマンドを実行します:

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

https://gitlab.com のパスワードを聞かれたら、個人アクセストークンを入力します。

clone コマンドのusername です:

  • 任意の文字列を指定できます。
  • 空文字列であってはなりません。

認証に依存するオートメーションパイプラインを設定する場合は、このことを覚えておいてください。

トラブルシューティング

個人アクセストークンの取り消し

個人アクセストークンが何らかの方法で誤って失効した場合、管理者はそのトークンを取り消すことができます。デフォルトでは、デイリージョブはシステム時間の午前1:00に失効したトークンを削除します。

caution
以下のコマンドを実行すると、データが直接変更されます。これは、正しく実行されなかったり、適切な条件下で実行されなかったりすると、損害を与える可能性があります。念のため、インスタンスのバックアップをリストアできる状態にして、まずテスト環境でこれらのコマンドを実行してください。
  1. Railsコンソールを開きます。
  2. トークンの取り消しを行います:

    token = PersonalAccessToken.find_by_token('<token_string>')
    token.update!(revoked:false)
    

    例えば、token-string-here123 のトークンを取り消すには、次のようにします:

    token = PersonalAccessToken.find_by_token('token-string-here123')
    token.update!(revoked:false)
    

個人アクセストークンに代わるもの

Git over HTTPS の場合は、アクセストークンの代わりにOAuth 認証ヘルパーを使うこともできます。