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

OAuth2が使えない場合は、個人アクセストークンを使ってGitLab APIで認証することができます。

個人アクセストークンをGitで使ってHTTPやSSHで認証することもできます。 個人アクセストークンは、二要素認証(2FA)が有効になっている場合に必要になります。 どちらの場合も、パスワードの代わりにトークンを使って認証することができます。

パーソナルアクセストークンの有効期限は、お客様が定義した日付の午前0時(UTC)です。

  • GitLabは毎日UTC午前01:00にチェックを行い、7日以内に期限が切れる個人アクセストークンを特定します。 これらのトークンのオーナーにはメールで通知されます。
  • GitLab Ultimateでは、管理者は個人アクセストークンの有効期限を制限することができます。
  • GitLab Ultimateでは、管理者は個人アクセストークンの有効期限を切り替えることができます。

個人アクセストークンを使用したAPI認証の例については、API Docsの以下のセクションを参照してください。

GitLab では、管理者が API 経由で作成するなりすましトークンも提供しています。 これは、特定のユーザーとしての認証を自動化するのに適しています。

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

個人アクセストークンはGitLabプロフィールから好きなだけ作成できます。

  1. GitLabにログインします。
  2. 右上のアバターをクリックし、「設定」を選択します。
  3. ユーザー設定]メニューで、[アクセストークン]を選択します。
  4. トークンの名前と有効期限を選択します。
  5. 希望のスコープを選択します。
  6. 個人アクセストークンの作成]ボタンをクリックします。
  7. 個人アクセストークンは安全な場所に保存してください。 一度ページを離れるか更新すると、再度アクセスすることはできません。

個人アクセストークンの失効

個人アクセストークンは、「アクティブな個人アクセストークン」エリアにある「アクセストークンの失効」ボタンをクリックすることで、いつでも失効させることができます。

トークンのアクティビティ

トークンが最後に使用された日時は、Personal Access Tokensページから確認できます。 トークンの使用状況の更新は24時間に1回に固定されています。APIリソースや GraphQL APIへのリクエストにより、トークンの使用状況が更新されます。

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

個人アクセストークンは、トークンが実行できるさまざまなアクションを許可する1つまたは複数のスコープで作成できます。 利用可能なスコープは、次の表のとおりです。

範囲 次で導入されました 説明
read_user GitLab 8.15 /users基本的に、Users APIGET リクエストはすべて許可されます。
api GitLab 8.15 すべてのグループとプロジェクト、コンテナレジストリ、およびパッケージレジストリを含む、APIへの完全な読み取り/書き込みアクセスを許可します。
read_api GitLab 12.10 すべてのグループとプロジェクト、コンテナレジストリ、パッケージレジストリを含む API への読み取りアクセスを許可します。
read_registry GitLab 9.3 プロジェクトが非公開で承認が必要な場合に、コンテナレジストリイメージの読み込み (pull) を許可します。
sudo GitLab 10.2 システム内の任意のユーザーとしてAPIアクションを実行できます(認証されたユーザーが管理者である場合)。
read_repository GitLab 10.7 git cloneを通してリポジトリへの読み取り専用アクセス(プル)を許可します。
write_repository GitLab 11.11 git cloneを通してリポジトリへの読み書きアクセス(プル、プッシュ)を許可します。 2FA が有効な場合に HTTP 経由で Git リポジトリにアクセスするために必要です。

プログラムによる個人アクセストークンの作成

自動化やテストで使うために、あらかじめ決められた個人アクセストークンをプログラムで作成することができます。 GitLabインスタンスのRailsコンソールセッションを実行するのに十分なアクセス権が必要です。

ユーザー名automation-botのユーザーのトークンを作成するには、Rails コンソール (sudo gitlab-rails console) で以下を実行します:

user = User.find_by_username('automation-bot')
token = user.personal_access_tokens.create(scopes: [:read_user, :read_repository], name: 'Automation token')
token.set_token('token-string-here123')
token.save!

GitLabRails 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'); token.set_token('token-string-here123'); token.save!"
注:トークン文字列の長さは20文字でなければ、パーソナルアクセストークンとして認識されません。

有効なスコープのリストとその機能はソースコードに記載されています。

プログラムによる個人アクセストークンの失効

個人アクセストークンをプログラムで取り消すことができます。 GitLab インスタンスのRails コンソールセッションを実行するには、十分なアクセス権が必要です。

既知のトークンtoken-string-here123を取り消すには、Rails コンソール (sudo gitlab-rails console) で以下を実行します:

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

GitLabRails Runnerを使えば、これを1行のシェルコマンドに短縮できます:

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