デプロイトークン

デプロイトークンを使用して、ユーザーアカウントに依存しないデプロイタスクの認証を有効にすることができます。ほとんどの場合、ビルドサーバーやCI/CDサーバーなどの外部ホストからデプロイトークンを使用します。

デプロイトークンを使用すると、自動タスクは以下のことが可能になります:

  • Git リポジトリのクローン。
  • GitLabコンテナレジストリからのプル、GitLabコンテナレジストリへのプッシュ。
  • GitLab パッケージレジストリからのプル、GitLab パッケージレジストリへのプッシュ。

デプロイトークンは値のペアです:

  • username: HTTP認証フレームワークのusername 。デフォルトのユーザー名形式はgitlab+deploy-token-{n} です。デプロイトークンの作成時に、カスタムユーザー名を指定できます。
  • token: HTTP 認証フレームワークのpassword

以下のエンドポイントへのHTTP 認証にデプロイトークンを使用できます:

デプロイトークンは、プロジェクトレベルでもグループレベルでも作成できます:

  • プロジェクト デプロイトークン:権限はプロジェクトにのみ適用されます。
  • グループデプロイトークン:権限はグループ内のすべてのプロジェクトに適用されます。

デフォルトでは、デプロイトークンに有効期限はありません。作成時にオプションで有効期限を設定できます。有効期限はその日の午前0時(UTC)に発生します。

caution
外部認証が有効になっている場合、新規または既存のデプロイトークンをGitオペレーションやパッケージレジストリオペレーションに使用することはできません。

スコープ

デプロイトークンのスコープは、デプロイトークンが実行できるアクションを決定します。

スコープ説明
read_repository git clone を使ってリポジトリに読み取り専用でアクセスします。
read_registryプロジェクトのコンテナレジストリ内のイメージへの読み取り専用アクセス。
write_registryプロジェクトのコンテナレジストリへの書き込みアクセス(プッシュ)。
read_package_registryプロジェクトのパッケージレジストリへの読み込み専用アクセス。
write_package_registryプロジェクトのパッケージレジストリへの書き込みアクセス。

GitLab デプロイトークン

GitLab デプロイトークンは特別なタイプのデプロイトークンです。gitlab-deploy-token という名前のデプロイトークンを作成すると、デプロイトークンは自動的にCI/CDパイプラインで使用するための変数としてCI/CDジョブに公開されます:

  • CI_DEPLOY_USER:ユーザー名
  • CI_DEPLOY_PASSWORD:トークン

たとえば、GitLab トークンを使って GitLab コンテナのレジストリにログインする場合:

docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY
note
GitLab 15.0 以前では、gitlab-deploy-token デプロイトークンの特別な処理はグループデプロイトークンでは機能しません。CI/CD ジョブでグループデプロイトークンを利用できるようにするには、Settings > CI/CD > VariablesCI_DEPLOY_USERCI_DEPLOY_PASSWORD CI/CD 変数をグループデプロイトークンの名前とトークンに設定します。

GitLab 公開 API

デプロイトークンは GitLab 公開 API では使えません。しかし、パッケージレジストリなど一部のエンドポイントではデプロイトークンを使うことができます。詳しくはレジストリでの認証をご覧ください。

デプロイトークンの作成

デプロイトークンを作成すると、ユーザーアカウントに依存せずに実行できるデプロイタスクを自動化できます。

前提条件:

  • 少なくともプロジェクトまたはグループのメンテナーのロールを持っている必要があります。
  1. 左側のサイドバーで、「検索」を選択するか、または「移動」を選択して、プロジェクトまたはグループを見つけます。
  2. 設定] > [リポジトリ]を選択します。
  3. デプロイトークン]を展開します。
  4. トークンの追加]を選択します。
  5. フィールドを入力し、必要なスコープを選択します。
  6. デプロイトークンの作成]を選択します。

デプロイトークンの値を記録します。ページを離れるか更新すると、再度アクセスすることはできません。

デプロイトークンの取り消し

トークンが不要になった場合、トークンを失効させます。

前提条件:

  • 少なくともプロジェクトまたはグループのメンテナーのロールを持っている必要があります。

デプロイトークンを取り消すには、以下の手順に従います:

  1. 左側のサイドバーで、「検索」を選択するか、または「移動」を選択して、プロジェクトまたはグループを見つけます。
  2. 設定] > [リポジトリ]を選択します。
  3. デプロイトークン]を展開します。
  4. Active Deploy Tokens] セクションで、取り消したいトークンの横にある [Revoke] を選択します。

リポジトリのクローン

デプロイトークンを使用してリポジトリをクローンできます。

前提条件:

  • read_repository スコープを持つデプロイトークン。

デプロイトークンを使ってリポジトリをクローンする例:

git clone https://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git

コンテナレジストリからのイメージの取得

デプロイトークンを使用して、コンテナレジストリからイメージをプルできます。

前提条件:

  • read_registry スコープを持つデプロイトークン。

デプロイトークンを使用してコンテナレジストリからイメージを取得する例:

docker login -u <username> -p <deploy_token> registry.example.com
docker pull $CONTAINER_TEST_IMAGE

コンテナレジストリへのイメージのプッシュ。

デプロイトークンを使用して、コンテナレジストリにイメージをプッシュできます。

前提条件:

  • write_registry スコープを持つデプロイトークン。

デプロイトークンを使用してコンテナレジストリにイメージをプッシュする例:

docker login -u <username> -p <deploy_token> registry.example.com
docker push $CONTAINER_TEST_IMAGE

パッケージレジストリからのパッケージのプル

GitLab 13.0から導入されました

デプロイトークンを使ってパッケージレジストリからパッケージを取り出せます。

前提条件:

  • read_package_registry スコープを持つデプロイトークン。

選択したパッケージタイプについて、デプロイトークンの認証手順に従ってください。

GitLab レジストリから NuGet パッケージをインストールする例:

nuget source Add -Name GitLab -Source "https://gitlab.example.com/api/v4/projects/10/packages/nuget/index.json" -UserName <username> -Password <deploy_token>
nuget install mypkg.nupkg

パッケージレジストリへのパッケージのプッシュ

GitLab 13.0から導入されました

デプロイトークンを使って GitLab パッケージレジストリにパッケージをプッシュすることができます。

前提条件:

  • write_package_registry スコープを持つデプロイトークン。

選択したパッケージタイプについて、デプロイトークンの認証手順に従ってください。

NuGetパッケージをパッケージレジストリに公開する例:

nuget source Add -Name GitLab -Source "https://gitlab.example.com/api/v4/projects/10/packages/nuget/index.json" -UserName <username> -Password <deploy_token>
nuget push mypkg.nupkg -Source GitLab

依存プロキシからイメージを引き出す

GitLab 14.2で導入されました

デプロイトークンを使って依存プロキシからイメージを引き出すことができます。

前提条件:

  • read_registry およびwrite_registry スコープを持つデプロイトークン。

依存プロキシ認証の指示に従ってください。