GitLab CI/CDジョブトークン

パイプラインジョブが実行されようとすると、GitLabはユニークなトークンを生成し、CI_JOB_TOKEN の定義済み変数 として注入します。

GitLab CI/CD ジョブトークンを使って、特定の API エンドポイントを認証することができます：

トークンは、ジョブを実行させたユーザーと同じ API アクセス権限を持っています。ユーザーは、コミットをプッシュする、手動ジョブをトリガーする、スケジュールされたパイプラインのオーナーになるなどのアクションを取ることで、ジョブを実行させることができます。したがって、このユーザーは必要な権限を持つロールに割り当てられていなければなりません。

トークンはパイプラインジョブが実行されている間のみ有効です。ジョブが終了すると、トークンは使用できなくなります。

ジョブトークンは設定なしでプロジェクトのリソースにアクセスできますが、必要のない権限を与えるかもしれません。アクセス権限をより戦略的に制御するために、この機能を再設計する提案があります。

CI/CDジョブで非公開プロジェクトからリポジトリを認証してクローンするためにジョブトークンを使うこともできます：

git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.example.com/<namespace>/<project>

リポジトリにプッシュするためにジョブトークンを使うことはできませんが、イシュー389060はこの振る舞いを変更することを提案しています。

GitLab CI/CD ジョブトークンのセキュリティ

このトークンが漏れないように、GitLab：

  • ジョブログのジョブトークンをマスクします。
  • ジョブが実行されているときのみ、ジョブトークンに権限を付与します。

このトークンが漏れないようにするために、Runnerもセキュアに設定する必要があります。避けてください：

  • Dockerprivileged 、マシンを再利用します。
  • 同じマシンでジョブを実行する場合、shell Executor を使用します。

GitLab Runnerの設定が安全でない場合、誰かが他のジョブからトークンを盗もうとするリスクが高まります。

CI/CD ジョブのトークンへのアクセス設定

CI/CD ジョブ トークンのセキュリティを高めるために、CI/CD ジョブ トークンがアクセスできるプロジェクトを制御できます。ジョブトークンは、特定の非公開リソースにアクセスするために必要でない余分な権限を与えるかもしれません。ジョブトークンのスコープは非公開プロジェクトへのアクセスのみを制御します。アクセストークンが公開プロジェクトや内部プロジェクトの場合は、トークンのスコープは適用されません。

もしジョブトークンが流出した場合、そのジョブトークンのユーザーの非公開データにアクセスするために使用される可能性があります。ジョブトークンのアクセススコープを制限することで、プロジェクトが明示的にアクセストークンされない限り、非公開データにアクセスできなくなります。

より戦略的なアクセス権限の制御を追加する提案があり、エピック3559を参照してください。

note
CI_REGISTRY_TOKEN は認証にCI_JOB_TOKEN を使用するので、アクセス設定はCI_REGISTRY_TOKEN にも適用されます。

ジョブトークンでプロジェクトへのアクセスを許可します。

CI_JOB_TOKEN を通してあなたのプロジェクトにアクセスできるプロジェクトの許可リストを作成します。

例えば、projectはA B allowlistに Bprojectを追加 Aすることができます。A B プロジェクト B A(A 「許可されたプロジェクト」)B のCI/CDジョブは B、CI/CDジョブのトークンを使ってAPIコールを認証し、プロジェクトにアクセスできるようになります。 AプロジェクトA が公開または内部の場合、プロジェクトB 、allowlistに追加しなくてもプロジェクトにアクセスできます。

デフォルトでは、プロジェクトのallowlistにはプロジェクト自身しか含まれません。

この機能を無効にすることはセキュリティリスクなので、プロジェクトのメンテナーやオーナーはこの設定を常に有効にしておくべきです。プロジェクトを横断的にアクセスする必要がある場合にのみ、プロジェクトを許可リストに追加してください。

ジョブトークンスコープの許可リストを無効にします。

GitLab16.3では、CI_JOB_TOKENの設定をLimit access_to_this projectに変更して、このプロジェクトへのアクセスを許可します。

caution
allowlistを無効にすることはセキュリティリスクです。悪意のあるユーザーが、許可されていないプロジェクトで作成されたパイプラインを侵害しようとする可能性があります。パイプラインがメンテナーによって作成された場合、ジョブトークンを使ってあなたのプロジェクトにアクセ スしようとする可能性があります。

テストや同様の理由でジョブトークンスコープの allowlist を無効にすることはできますが、できるだけ早く有効にしてください。

前提条件

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

ジョブトークンスコープを無効にするには allowlist：

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. Settings > CI/CDを選択します。
  3. アクセストークンを展開します。
  4. この_プロジェクトへの_アクセス制限を無効に切り替えます。新規プロジェクトではデフォルトで有効です。

APIでallowlistを無効にすることもできます。

ジョブトークンスコープのallowlistにプロジェクトを追加します。

GitLab16.3では、CI_JOB_TOKENの設定をLimit access_to_this projectに変更して、このプロジェクトへのアクセスを許可します。

プロジェクトの allowlist にプロジェクトを追加することができます。許可リストに追加されたプロジェクトは、CI/CD ジョブトークンを使って実行中のパイプラインから API 呼び出しを行うことができます。

前提条件

  • 現在のプロジェクトで少なくともメンテナーのロールを持っている必要があります。許可されたプロジェクトが内部または非公開の場合、そのプロジェクトで少なくともゲストロールを持っている必要があります。
  • 200以上のプロジェクトを許可リストに追加してはいけません。

プロジェクトを追加するには

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. Settings > CI/CDを選択します。
  3. アクセストークンを展開します。
  4. この_プロジェクトへの_アクセス制限が有効になっていることを確認します。
  5. Allow CI job tokens from the following projects to access this project] で、プロジェクトを許可リストに追加します。

APIを使用して、対象のプロジェクトをallowlistに追加することもできます。

プロジェクトのジョブトークンアクセスの制限

note
この機能はすべての新規プロジェクトでデフォルトで無効になっており、GitLab 17.0で削除される予定です。プロジェクトのメンテナーやオーナーは、代わりにアクセスコントロールを有効にしてください。

プロジェクトのジョブトークンがアクセスできるプロジェクトの許可リストを作成することで、プロジェクトのジョブトークンの範囲をコントロールできます。

デフォルトでは、許可リストには現在のプロジェクトが含まれます。他のプロジェクトは、両方のプロジェクトにアクセスできるメンテナーが追加したり削除したりできます。

この設定を無効にすると、すべてのプロジェクトがallowlistに含まれ、ジョブトークンはユーザーのアクセストークン権限によってのみ制限されます。

例えば、この設定が有効な場合、プロジェクトA のパイプラインのジョブはCI_JOB_TOKEN のスコープがプロジェクトA. ANET に制限されます。Aジョブがトークンを使用して非公開プロジェクトにAPIリクエストを行う必要がある場合B、 Ballowlist for . AプロジェクトがB 公開または内部の場合は B、アクセスを許可するためにallowlistに追加するB 必要は Bありません。

ジョブトークンスコープの設定

Limit CI_JOB_TOKEN accesssetting は GitLab 16.3 でLimit access_from_this projectに名称変更されました。

前提条件

  • トークンのスコープに追加されたプロジェクトが200を超えていないこと。

ジョブトークンのスコープを設定するには、以下の手順に従います：

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. Settings > CI/CDを選択します。
  3. アクセストークンを展開します。
  4. この_プロジェクトからの_アクセスを制限する] を有効に切り替えます。
  5. オプション。既存のプロジェクトをアクセストークンのアクセス範囲に追加します。プロジェクトを追加するユーザーは、両方のプロジェクトでメンテナーのロールを持っている必要があります。

別のパイプラインからアーティファクトをダウンロード

CI_JOB_TOKEN API を使ったアーティファクトのダウンロードは GitLab 9.5 で導入されました。

CI_JOB_TOKEN を使って、以前のパイプラインで作成されたジョブのアーティファクトにアクセスすることができます。アーティファクトを取得したいジョブを指定する必要があります：

build_submodule:
  stage: test
  script:
    - apt update && apt install -y unzip
    - curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/download?job=test&job_token=$CI_JOB_TOKEN"
    - unzip artifacts.zip

ジョブのアーティファクトAPIについての詳細はこちらをご覧ください。

トラブルシューティング

CIジョブトークンの失敗は通常、404 Not Found のようなレスポンスとして表示されます：

  • 未承認の Git クローンです：

     $ git clone https://gitlab-ci-token:$CI_JOB_TOKEN@gitlab.com/fabiopitino/test2.git
   
 Cloning into 'test2'...
 remote: The project you were looking for could not be found or you don't have permission to view it.
 fatal: repository 'https://gitlab-ci-token:[MASKED]@gitlab.com/<namespace>/<project>.git/' not found

  • 不正なパッケージのダウンロード：

     $ wget --header="JOB-TOKEN: $CI_JOB_TOKEN" ${CI_API_V4_URL}/projects/1234/packages/generic/my_package/0.0.1/file.txt
   
 --2021-09-23 11:00:13--  https://gitlab.com/api/v4/projects/1234/packages/generic/my_package/0.0.1/file.txt
 Resolving gitlab.com (gitlab.com)... 172.65.251.78, 2606:4700:90:0:f22e:fbec:5bed:a9b9
 Connecting to gitlab.com (gitlab.com)|172.65.251.78|:443... connected.
 HTTP request sent, awaiting response... 404 Not Found
 2021-09-23 11:00:13 ERROR 404: Not Found.

  • 不正な API リクエストです：

     $ curl --verbose --request POST --form "token=$CI_JOB_TOKEN" --form ref=master "https://gitlab.com/api/v4/projects/1234/trigger/pipeline"
   
 < HTTP/2 404
 < date: Thu, 23 Sep 2021 11:00:12 GMT
 {"message":"404 Not Found"}
 < content-type: application/json

CI/CDジョブトークン認証のトラブルシューティングでは、以下のことに注意してください：

  • プロジェクトごとにスコープ設定を切り替えるために、GraphQLのサンプル変異が利用可能です。
  • このコメントでは、BashとcURLを使用してgraphQLを使用する方法を示します：
    • インバウンドトークンのアクセススコープを有効にします。
    • プロジェクトAからプロジェクトBへのアクセスを許可するか、BをAの許可リストに追加します。
    • プロジェクトアクセスを削除するには
  • CI/CD ジョブ トークンのスコープが有効で、ジョブ トークンが別のプロジェクトにアクセスするために使用されている場合：
    • ジョブを実行するユーザーは、アクセスされるプロジェクトのメンバーでなければなりません。
    • ユーザーはアクションを実行する権限を持っている必要があります。
    • アクセスするプロジェクトは、アクセスしようとするプロジェクトが許可リストに追加されている必要があります。
  • CIジョブトークンは、ジョブが実行中でない場合、抹消された場合、またはプロジェクトが削除されつつある場合には無効になります。