CI/CDパイプライン

CI/CDパイプラインは、GitLab CI/CDの基本的な構成要素です。パイプラインは、.gitlab-ci.ymlファイルでYAMLキーワードを使用して設定されます。

パイプラインは、ブランチへのプッシュ、マージリクエストの作成、設定されたスケジュールなど、特定のイベントが発生した際に自動的に実行するよう設定できます。必要な場合は、パイプラインを手動で実行することもできます。

パイプラインは以下で構成されています:

• プロジェクトのパイプラインの全体的な動作を制御するグローバルYAMLキーワード。
• タスクを実行するためのコマンドを実行するジョブ。たとえば、ジョブはコードをコンパイル、テスト、またはデプロイできます。ジョブは互いに独立して、Runnerによって実行されます。
• ジョブをグループ化する方法を定義するステージ。ステージは順番に実行されますが、ステージ内のジョブは並行して実行されます。たとえば、アーリーステージのジョブではコードのlintやコンパイルを実行するのに対して、後のステージのジョブではコードのテストやデプロイを実行できます。ステージ内のすべてのジョブが成功すると、パイプラインは次のステージに進みます。ステージ内のいずれかのジョブが失敗した場合、次のステージは（通常は）実行されず、パイプラインは途中で終了します。

小規模なパイプラインは、次の順序で実行される3つのステージで構成できます:

• プロジェクトのコードをコンパイルするcompileというジョブを含むbuildステージ。
• コードに対してさまざまなテストを実行するtest1とtest2という2つのジョブを含むtestステージ。これらのテストは、compileジョブが正常に完了した場合にのみ実行されます。
• deploy-to-productionというジョブがあるdeployステージ。このジョブは、testステージの両方のジョブが開始され、正常に完了した場合にのみ実行されます。

初めてのパイプラインを開始するには、初めてのGitLab CI/CDパイプラインを作成して実行するを参照してください。

パイプラインの種類

パイプラインは、さまざまな方法で設定できます:

• 基本的なパイプラインでは、各ステージのすべてのジョブを同時に実行し、その後に次のステージを実行します。
• needsキーワードを使用するパイプラインは、ジョブ間の依存関係に基づいて実行され、基本的なパイプラインよりも速く実行できます。
• マージリクエストパイプラインは、（すべてのコミットではなく）マージリクエストに対してのみ実行されます。
• マージ結果パイプラインは、ソースブランチからの変更がすでにターゲットブランチにマージされているかのように動作するマージリクエストパイプラインです。
• マージトレインは、マージ結果パイプラインを使用して、マージを順番にキューに入れます。
• 親子パイプラインは、複雑なパイプラインを、複数の子サブパイプラインをトリガーできる1つの親パイプラインに分割します。これらはすべて同じプロジェクト内で同じSHAで実行されます。このパイプラインアーキテクチャは、一般的にモノリポジトリで使用されます。
• マルチプロジェクトパイプラインは、異なる複数のプロジェクトのパイプラインを結合します。

パイプラインを設定する

パイプラインとその構成要素であるジョブやステージは、各プロジェクトのCI/CDパイプライン設定ファイルにYAMLキーワードを使用して定義されます。GitLabでCI/CD設定を編集するときは、パイプラインエディタを使用する必要があります。

GitLab UIを使用してパイプラインの特定の側面を設定することもできます:

• 各プロジェクトのパイプライン設定。
• パイプラインスケジュール。
• カスタムCI/CD変数。

VS Codeを使用してGitLab CI/CD設定を編集する場合、VS Code用GitLab Workflow拡張機能を使用すると、設定を検証し、パイプラインのステータスを表示できます。

手動でパイプラインを実行する

パイプラインは、定義済み変数、または手動で指定された変数を使用して、手動で実行できます。

パイプラインの結果（たとえば、コードビルド）がパイプラインの標準的な操作以外で必要な場合に、手動で実行することがあります。

パイプラインを手動で実行するには、次の手順を実行します:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
2. ビルド > パイプラインを選択します。
3. 新しいパイプラインを選択します。
4. ブランチ名またはタグで実行フィールドで、パイプラインを実行するブランチまたはタグを選択します。
5. オプション。以下を入力します:
   • パイプラインを実行するために必要な入力。入力のデフォルト値は事前入力されていますが、変更可能です。入力値は、予期される型に従ったものでなければなりません。
   • CI/CD変数。フォームに値が事前入力されるように変数を設定できます。パイプラインの動作を制御するために入力を使用すると、CI/CD変数よりもセキュリティと柔軟性が向上します。
6. 新しいパイプラインを選択します。

これでパイプラインは設定どおりにジョブを実行するようになります。

マニュアルパイプライン変数を表示する

パイプラインを手動で実行するときに指定されたすべての変数を確認できます。

前提要件:

• プロジェクトのオーナーロールが必要です。

必要なロールは実行する内容によって異なります:

マニュアルパイプライン変数を参照するには、次の手順に従います:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
2. 設定 > CI/CDを選択します。
3. パイプライン変数を表示するを選択します。
4. ビルド > パイプラインに移動し、手動で実行されたパイプラインを選択します。
5. マニュアル変数タブを選択します。

変数の値は、デフォルトでマスクされます。少なくともデベロッパーロールをお持ちの場合は、目のアイコンを選択して値を表示できます。

手動パイプラインの変数を事前入力する

descriptionおよびvalueキーワードを使用して、パイプラインを手動で実行するときに事前入力されるパイプラインレベル（グローバル）変数を定義できます。descriptionは、変数の用途や許容値などの情報を説明するために使用します。説明にはMarkdownを使用できます。

ジョブレベル変数は事前入力できません。

手動でトリガーされるパイプラインでは、新しいパイプラインページに、.gitlab-ci.ymlファイルでdescriptionが定義されているパイプラインレベルの変数がすべて表示されます。説明は変数の下に表示されます。

事前入力された値は変更できます。変更すると、その単一のパイプライン実行のみに対して値がオーバーライドされます。このプロセスでオーバーライドされた変数は展開され、マスクされません。設定ファイルで変数のvalueを定義しない場合、変数名は一覧表示されますが、値フィールドは空白になります。

次に例を示します:

variables:
  DEPLOY_CREDENTIALS:
    description: "The deployment credentials."
  DEPLOY_ENVIRONMENT:
    description: "Select the deployment target. Valid options are: 'canary', 'staging', 'production', or a stable branch of your choice."
    value: "canary"

この例では:

• DEPLOY_CREDENTIALSは新しいパイプラインページに表示されますが、値は設定されていません。ユーザーは、パイプラインを手動で実行するたびに値を定義する必要があります。
• DEPLOY_ENVIRONMENTは、新しいパイプラインページでデフォルト値としてcanaryが事前入力され、メッセージにはその他のオプションについての説明があります。

選択可能な事前入力される変数値のリストを設定する

パイプラインを手動で実行するときにユーザーが選択できるCI/CD変数値の配列を定義できます。これらの値は、新しいパイプラインページのドロップダウンリストに表示されます。optionsに値オプションのリストを追加し、valueでデフォルト値を設定します。valueの文字列もoptionsリストに含める必要があります。

次に例を示します:

variables:
  DEPLOY_ENVIRONMENT:
    value: "staging"
    options:
      - "production"
      - "staging"
      - "canary"
    description: "The deployment target. Set to 'staging' by default."

URLクエリ文字列を使用してパイプラインを実行する

クエリ文字列を使用して、新しいパイプラインページに自動入力できます。たとえば、クエリ文字列が.../pipelines/new?ref=my_branch&var[foo]=bar&file_var[file_foo]=file_barなら、新しいパイプラインページに次の内容が自動入力されます:

• Run for（実行）フィールド: my_branch。
• 変数セクション:
  • 変数:
    • キー: foo
    • 値: bar
  • ファイル:
    • キー: file_foo
    • 値: file_bar

pipelines/new URLの形式は次のとおりです:

.../pipelines/new?ref=<branch>&var[<variable_key>]=<value>&file_var[<file_key>]=<value>

次のパラメータがサポートされています:

• ref: Run for（実行）フィールドに入力するブランチを指定します。
• var: Variable変数を指定します。
• file_var: File変数を指定します。

varまたはfile_varごとに、キーと値が必要です。

パイプラインに手動操作を追加する

手動ジョブを使用すると、パイプラインを進める前に手動での操作が必要になります。

これは、パイプライングラフから直接行うことができます。特定のジョブを実行するには、実行（ ）を選択します。

たとえば、パイプラインは自動的に開始できますが、本番環境にデプロイするには手動アクションが必要、というようにできます。次の例の場合、productionステージに手動アクションを含むジョブがあります:

ステージ内のすべての手動ジョブを開始する

ステージに手動ジョブのみが含まれている場合は、ステージの上にあるすべての手動ジョブを実行（ ）を選択して、すべてのジョブを同時に開始できます。ステージに手動以外のジョブが含まれている場合、このオプションは表示されません。

パイプラインをスキップする

パイプラインをトリガーせずにコミットをプッシュするには、コミットメッセージに、大文字と小文字を区別せずに、[ci skip]または[skip ci]を追加します。

または、Git 2.10以降では、ci.skip Gitプッシュオプションを使用します。ci.skipプッシュオプションは、マージリクエストパイプラインをスキップしません。

パイプラインを削除する

プロジェクトのオーナーロールを持つユーザーは、パイプラインを削除できます:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
2. ビルド > パイプラインを選択します。
3. 削除するパイプラインのパイプラインID（#123456789など）またはパイプラインのステータスアイコン（成功など）を選択します。
4. パイプラインの詳細ページの右上にある削除を選択します。

パイプラインを削除しても、子パイプラインは自動的に削除されません。詳細については、イシュー39503を参照してください。

保護ブランチでのパイプラインセキュリティ

保護ブランチでパイプラインが実行される場合、厳格なセキュリティモデルが適用されます。

ユーザーが特定のブランチへのマージまたはプッシュを許可されている場合、保護ブランチでは次のアクションが許可されます:

• 手動パイプラインの実行（Web UIまたはパイプラインAPIを使用）。
• スケジュールされたパイプラインの実行。
• トリガーを使用したパイプラインの実行。
• オンデマンドDASTスキャンの実行。
• 既存のパイプラインでの手動アクションのトリガー。
• 既存のジョブの再試行またはキャンセル（Web UIまたはパイプラインAPIを使用）。

保護としてマークされた変数は、保護ブランチのパイプラインで実行されるジョブからアクセスできます。デプロイ認証情報やトークンなどの機密情報にアクセスする権限があるユーザーにのみ、保護ブランチにマージする権限を割り当てます。

保護としてマークされたRunnersは、保護ブランチでのみジョブを実行できます。信頼できないコードが保護されたRunnerで実行されるのを防ぎ、デプロイキーやその他の認証情報が誤ってアクセスされるのを防ぎます。保護されたRunnerで実行されるように設計されたジョブが標準のRunnerを使用しないようにするには、適切にタグ付けする必要があります。

保護された変数とRunnerへのアクセスがマージリクエストパイプラインのコンテキストでどのように機能するかを確認してください。

パイプラインを保護するための追加のセキュリティに関する推奨事項については、デプロイの安全性ページを確認してください。

アップストリームプロジェクトが再ビルドされたときにパイプラインをトリガーする（非推奨）

別のプロジェクトのタグに基づいてパイプラインを自動的にトリガーするようにプロジェクトを設定できます。サブスクライブされたプロジェクトの新しいタグパイプラインが完了すると、タグパイプラインの成功、失敗、またはキャンセルに関係なく、プロジェクトのデフォルトブランチでパイプラインがトリガーされます。

別のパイプラインが実行されたときにパイプラインをトリガーするには、代わりにパイプライントリガートークンを使用したCI/CDジョブを使用できます。この方法は、パイプラインサブスクリプションよりも信頼性が高く柔軟性があり、推奨されるアプローチです。

前提要件:

• アップストリームプロジェクトは公開されている必要があります。
• ユーザーはアップストリームプロジェクトでデベロッパーロールを持っている必要があります。

アップストリームプロジェクトが再ビルドされたときにパイプラインをトリガーするには、次の手順を実行します:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
2. 設定 > CI/CDを選択します。
3. パイプラインのサブスクリプションを展開します。
4. プロジェクトを追加を選択します。
5. サブスクライブするプロジェクトを<namespace>/<project>形式で入力します。たとえば、プロジェクトがhttps://gitlab.com/gitlab-org/gitlabの場合は、gitlab-org/gitlabを使用します。
6. サブスクライブを選択します。

アップストリームパイプラインサブスクリプションの最大数は、アップストリームプロジェクトとダウンストリームプロジェクトの両方において、デフォルトで2です。GitLab Self-Managedでは、管理者がこの制限を変更できます。

パイプラインの所要時間の計算方法

パイプラインの合計実行時間には、以下は含まれません:

• 再試行または手動で再実行されたジョブの初回実行の所要時間。
• 待機（キュー）時間。

つまり、ジョブが再試行または手動で再実行された場合、最新の実行の所要時間のみが合計実行時間に含まれます。

各ジョブはPeriodとして表されます。これは以下で構成されます:

• Period#first（ジョブの開始時）。
• Period#last（ジョブの終了時）。

簡単な例を次に示します:

• A (0, 2)
• A’ (2, 4)
  • これはAを再試行しています
• B (1, 3)
• C (6, 7)

この例では、次のようになります:

• Aは0で始まり、2で終わります。
• A’は2で始まり、4で終わります。
• Bは1で始まり、3で終わります。
• Cは6で始まり、7で終わります。

視覚的には、次のように表示できます:

0  1  2  3  4  5  6  7
AAAAAAA
   BBBBBBB
      A'A'A'A
                  CCCC

Aがリトライされるため無視され、ジョブA’のみがカウントされます。B、A’、およびCの結合は(1, 4)および(6, 7)です。したがって、合計実行時間は次のようになります:

(4 - 1) + (7 - 6) => 4

パイプラインを表示する

プロジェクトで実行されたすべてのパイプラインを表示するには、次の手順を実行します:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
2. ビルド > パイプラインを選択します。

次の条件でパイプラインページをフィルタリングできます:

• トリガー作成者
• ブランチ名
• ステータス
• タグ
• ソース

右上にあるドロップダウンリストでパイプラインIDを選択すると、インスタンス全体で一意のIDであるパイプラインIDが表示されます。pipeline IID（パイプラインIID）を選択すると、パイプラインIID（内部ID、プロジェクト内でのみ一意）が表示されます。

次に例を示します:

特定のマージリクエストに関連するパイプラインを表示するには、マージリクエストのパイプラインタブに移動します。

パイプラインの詳細

パイプラインを選択して、パイプライン内のすべてのジョブを表示するパイプラインの詳細ページを開きます。このページから、実行中のパイプラインのキャンセル、失敗したジョブの再試行、またはパイプラインの削除を実行できます。

パイプラインの詳細ページには、パイプライン内のすべてのジョブのグラフが表示されます:

標準URLを使用して、特定のパイプラインの詳細にアクセスできます:

• gitlab.example.com/my-group/my-project/-/pipelines/latest: プロジェクト内のデフォルトブランチの最新のコミットに対する、最新のパイプラインの詳細ページ。
• gitlab.example.com/my-group/my-project/-/pipelines/<branch>/latest: プロジェクトの<branch>ブランチの最新のコミットに対する、最新のパイプラインの詳細ページ。

ステージまたはneeds設定でジョブをグループ化する

needsキーワードを使用してジョブを設定する場合、パイプライン詳細ページでジョブをグループ化する方法は2通りあります。ステージ設定でジョブをグループ化するには、ジョブをグループ化セクションでstage（ステージ）を選択します:

needs設定によってジョブをグループ化するには、ジョブの依存関係を選択します。必要に応じて、依存関係を表示を選択すると、依存関係にあるジョブ間に線を表示できます。

左端の列のジョブが最初に実行され、それらに依存するジョブが次の列にグループ化されます。この例では:

• lint-jobは、needs: []が設定されており、どのジョブにも依存しないため、testステージにありますが、最初の列に表示されます。
• test-job1はbuild-job1に依存し、test-job2はbuild-job1とbuild-job2の両方に依存するため、両方のテストジョブが2列目に表示されます。
• 両方のdeployジョブは2列目のジョブ（それ自体が他の先行ジョブに依存する）に依存するため、デプロイジョブは3列目に表示されます。

ジョブの依存関係表示でジョブにカーソルを合わせると、選択したジョブの前に実行する必要があるすべてのジョブが強調表示されます:

パイプラインミニグラフ

パイプラインミニグラフは占有スペースが少なく、すべてのジョブが成功したか、失敗したジョブがあるかを一目で確認できます。単一のコミットに関連するすべてのジョブと、パイプラインの各ステージの最終結果を示しています。何が失敗したかをすばやく確認して修正できます。

パイプラインミニグラフは常にステージごとにジョブをグループ化し、パイプラインやコミットの詳細を表示するときにGitLabの各所で表示されます。

パイプラインミニグラフのステージは展開できます。各ステージにマウスカーソルを合わせ、名前とステータスを確認し、ステージを選択してジョブリストを展開します。

ダウンストリームパイプライングラフ

パイプラインにダウンストリームパイプラインをトリガーするジョブが含まれている場合、パイプラインの詳細表示とミニグラフでダウンストリームパイプラインを表示できます。

パイプラインの詳細表示では、パイプライングラフの右側に、トリガーされたダウンストリームパイプラインごとにカードが表示されます。カードにカーソルを合わせ、どのジョブがダウンストリームパイプラインをトリガーしたかを確認します。カードを選択して、パイプライングラフの右側にダウンストリームパイプラインを表示します。

パイプラインミニグラフでは、トリガーされたすべてのダウンストリームパイプラインのステータスが、ミニグラフの右側に追加のステータスアイコンとして表示されます。ダウンストリームパイプラインのステータスアイコンを選択して、そのダウンストリームパイプラインの詳細ページに移動します。

パイプラインの成功と期間のチャート

パイプライン分析は、CI/CDの分析ページで確認できます。

パイプラインバッジ

パイプラインステータスとテストカバレッジレポートバッジは、各プロジェクトで使用および設定できます。パイプラインバッジをプロジェクトに追加する方法については、パイプラインバッジを参照してください。

パイプラインAPI

GitLabは、次の目的でAPIエンドポイントを提供します:

• 基本的な機能を実行するため。詳細については、パイプラインAPIを参照してください。
• パイプラインスケジュールを管理するため。詳細については、パイプラインスケジュールAPIを参照してください。
• パイプラインの実行をトリガーするため。詳細については、以下を参照してください:
  • APIでパイプラインをトリガーする。
  • パイプライントリガーAPI。

Runnerのrefspec

Runnerがパイプラインジョブを取得すると、GitLabはそのジョブのメタデータを提供します。これには、Git refspecが含まれます。Git refspecは、どのref（ブランチまたはタグなど）とコミット（SHA1）をプロジェクトリポジトリからチェックアウトするかを定義します。

以下の表に、各パイプラインタイプに挿入されるrefspecを示します:

refs/heads/<name>とrefs/tags/<name>のrefは、プロジェクトリポジトリに存在します。GitLabは、パイプラインジョブの実行中に特別なref（refs/pipelines/<id>）を生成します。このrefは、関連付けられているブランチまたはタグが削除された後でも作成される場合があります。そのため、環境の自動停止やブランチ削除後にパイプラインを実行する可能性のあるマージトレインなどの一部の機能で役立ちます。

トラブルシューティング

ユーザー削除後もパイプラインサブスクリプションが継続する

ユーザーがGitLab.comアカウントを削除しても、削除は7日間行われません。この期間中、そのユーザーが作成したパイプラインサブスクリプションは、そのユーザーの元の権限で引き続き実行されます。不正なパイプライン実行を防ぐため、削除されたユーザーのパイプラインサブスクリプション設定は、すぐに更新してください。

New Pipeline（新しいパイプライン）ページに事前入力された変数が表示されない

パイプラインの定義済み変数が別のファイルで定義されている場合、New Pipeline（新しいパイプライン）ページに表示されないことがあります。別のファイルにアクセスする権限が必要です。そうでない場合、定義済みの変数を表示できません。