デプロイトークン

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

デプロイトークンを使用すると、個々のユーザーアカウントに権限を関連付けなくても、GitLabリソースへの安全なアクセスを提供できます。Git操作、コンテナレジストリ、パッケージレジストリで使用すると、デプロイの自動化に必要なものだけにアクセスできます。

デプロイトークンを使用すると、以下を実現できます:

自動化システムから個人の認証情報を削除することで、より安全なデプロイを実現
トークンごとに特定の権限を付与して、きめ細かいアクセス制御を実現
組み込みの認証変数を使用して、CI/CDパイプラインを簡素化
チームメンバーが変更された場合でも中断されない信頼性の高いデプロイプロセスを実現
専用のトークンIDでデプロイを追跡することで、監査証跡を改善
外部ビルドシステムおよびデプロイツールとシームレスに統合

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

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

デプロイトークンは、SSH認証をサポートしていません。

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

GitLabパッケージレジストリパブリックAPI。
Gitコマンド。
GitLab仮想レジストリパッケージ操作。

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

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

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

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

スコープ

デプロイトークンのスコープによって、実行できるアクションが決まります。

スコープ	説明
`read_repository`	`git clone`を使用したリポジトリへの読み取り専用アクセス。
`read_registry`	プロジェクトのコンテナレジストリ内のイメージへの読み取り専用アクセス。
`write_registry`	プロジェクトのコンテナレジストリへの書き込みアクセス。イメージをプッシュするには、読み取りアクセスと書き込みアクセスの両方が必要です。
`read_virtual_registry`	プロジェクトがプライベートで、認証が必要な場合は、依存プロキシを介して、コンテナイメージへの読み取り専用アクセス権を付与します。依存プロキシが有効になっている場合にのみ使用できます。
`write_virtual_registry`	プロジェクトがプライベートで、認証が必要な場合は、依存プロキシを介して、コンテナイメージへの読み取り、書き込み（プッシュ）、および削除アクセス権を付与します。依存プロキシが有効になっている場合にのみ使用できます。
`read_package_registry`	プロジェクトのパッケージレジストリへの読み取り専用アクセス。
`write_package_registry`	プロジェクトのパッケージレジストリへの書き込みアクセス。

GitLabデプロイトークン

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

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

たとえば、GitLabトークンを使用してGitLabコンテナレジストリにサインインするには、次のコマンドを実行します:

echo "$CI_DEPLOY_PASSWORD" | docker login $CI_REGISTRY -u $CI_DEPLOY_USER --password-stdin

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

グループでgitlab-deploy-tokenが定義されている場合、CI_DEPLOY_USERとCI_DEPLOY_PASSWORDのCI/CD変数は、グループ直下の子プロジェクトでのみ使用できます。

デプロイトークンの有効期限

この機能の利用可否は、機能フラグによって制御されます。詳細については、履歴を参照してください。

デプロイトークンは、定義した日付の午前0時（UTC）に有効期限が切れます。

GitLabは毎日午前1時（UTC）に、有効期限が近づいているデプロイトークンを確認します。これらのトークンの有効期限が切れる60日前、30日前、7日前に、プロジェクトオーナーとメンテナーにメールで通知が送信されます。

これらのメール通知は、アクティブ（失効していない）なデプロイトークンに対して、インターバルごとに1回のみ送信されます。

GitLabデプロイトークンのセキュリティ

GitLabデプロイトークンは有効期間が長いため、攻撃者にとって魅力的です。

デプロイトークンの漏えいを防ぐために、Runnerも安全に設定する必要があります:

マシンが再利用される場合は、Docker privilegedモードの使用を避ける必要があります。
複数のジョブが同じマシンで実行される場合は、shell executorを使用しない。

脆弱なGitLab Runnerの設定は、他のジョブからのトークンの盗難リスクを増大させます。

GitLabパブリックAPI

デプロイトークンは、GitLabパブリックAPIでは使用できません。ただし、パッケージレジストリのエンドポイントなど、一部のエンドポイントではデプロイトークンを使用できます。URLに文字列packages/<format>が含まれていると、エンドポイントがパッケージレジストリに属していると判断できます。例: https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt。詳細については、レジストリを使用した認証を参照してください。

デプロイトークンを作成する

ユーザーアカウントとは独立して実行できるデプロイタスクを自動化するためのデプロイトークンを作成します。

前提要件:

グループデプロイトークンを作成するには、グループのオーナーロールが必要です。
プロジェクトデプロイトークンを作成するには、プロジェクトのメンテナーロール以上が必要です。

左側のサイドバーで、検索または移動先を選択して、プロジェクトまたはグループを見つけます。
設定 > リポジトリを選択します。
デプロイトークンを展開します。
トークンの追加を選択します。
フィールドに入力し、目的のスコープを選択します。
デプロイトークンを作成を選択します。

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

デプロイトークンを取り消す

不要になったトークンを取り消します。

前提要件:

グループデプロイトークンを取り消すには、グループのオーナーロールが必要です。
プロジェクトデプロイトークンを取り消すには、プロジェクトのメンテナーロール以上が必要です。

デプロイトークンを取り消すには:

左側のサイドバーで、検索または移動先を選択して、プロジェクトまたはグループを見つけます。
設定 > リポジトリを選択します。
デプロイトークンを展開します。
Active Deploy Tokens（アクティブなデプロイトークン）セクションで、取り消すトークンの横にある取り消しを選択します。

リポジトリのクローンを作成する

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

前提要件:

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

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

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

コンテナレジストリからイメージをプルする

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

前提要件:

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

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

echo "$DEPLOY_TOKEN" | docker login -u <username> --password-stdin registry.example.com
docker pull $CONTAINER_TEST_IMAGE

コンテナレジストリにイメージをプッシュする

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

前提要件:

read_registryとwrite_registryのスコープを持つデプロイトークン。

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

echo "$DEPLOY_TOKEN" | docker login -u <username> --password-stdin registry.example.com
docker push $CONTAINER_TEST_IMAGE

パッケージレジストリからパッケージをプルする

デプロイトークンを使用して、パッケージレジストリからパッケージをプルできます。

前提要件:

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パッケージレジストリにパッケージをプッシュできます。

前提要件:

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

依存プロキシからイメージをプルする

デプロイトークンを使用して、依存プロキシからイメージをプルできます。

前提要件:

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

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