CI/CDパイプライン

note
GitLabのCI/CDパイプラインの包括的なデモを見るには、“Mastering continuous software development “ウェブキャストをご覧ください。

パイプラインは、継続的なインテグレーション、デリバリ、デプロイメントのトップレベルのコンポーネントです。

パイプラインの構成は、以下のとおりです。

  • ジョブとは、をするかを定義するものです。例えば、コードをコンパイルしたり、テストしたりするジョブがあげられます。
  • ステージとは、ジョブを実行するタイミングを定義するものです。例えば、テストを実行するステージは、コードをコンパイルするステージの後に実行するなどです。

ジョブはRunner によって実行されます。同じステージの複数のジョブは、十分な数の同時実行ランナーがいれば並行して実行されます。

ステージ内のすべてのジョブが成功すれば、パイプラインは次のステージに進みます。

あるステージのジョブがどこかで失敗すると、一般的に次のステージは実行されず、パイプラインはそこで終了します。

通常パイプラインは自動的に実行され、一度作成されたパイプラインへ介入する必要はありません。しかし、手動でパイプラインとやり取りする場合もあります。

典型的なパイプラインは、以下の順序で実行される4つのステージで構成されています。

  • build compile というジョブのステージ。
  • test1test2 という2つのジョブを持つtest ステージ。
  • staging deploy-to-stage というジョブのステージ。
  • production deploy-to-prod というジョブのステージ。
note
GitLab がプルするミラーリポジトリがある場合は、プロジェクトの設定 > リポジトリ > ミラーリポジトリ > ミラー更新のパイプラインをトリガーするでパイプラインのトリガーを有効にする必要があるかもしれません。

パイプラインの種類

パイプラインは様々な方法で設定できます。

パイプラインの設定

パイプラインとそれを構成するジョブおよびステージは、各プロジェクトのCI/CDパイプライン設定ファイルに定義されています。

  • ジョブは基本的な設定コンポーネントです。
  • ステージはstages キーワードを使って定義します。

CIパイプラインファイルの設定オプションの一覧は、GitLab CI/CDパイプライン設定リファレンスを参照してください。

GitLab UIから、パイプラインの特定部分を設定も可能です。

ランナーの参照仕様

Runnerがパイプラインジョブを選択すると、GitLabはそのジョブのメタデータを提供します。これにはGit refspecs が含まれ、プロジェクトのリポジトリからどの参照(ブランチやタグなど)とコミット(SHA1)をチェックアウトしたかを示します。

この表は、パイプラインの種類ごとに注入される refspecs の一覧です:

パイプラインタイプレフスペック
ブランチ用パイプライン +<sha>:refs/pipelines/<id>+refs/heads/<name>:refs/remotes/origin/<name>
タグ用パイプライン +<sha>:refs/pipelines/<id>+refs/tags/<name>:refs/tags/<name>
マージリクエストパイプライン+refs/pipelines/<id>:refs/pipelines/<id>

参照refs/heads/<name>refs/tags/<name> はプロジェクトリポジトリに存在します。GitLab は実行中のパイプラインジョブの間に特別な参照refs/pipelines/<id> を生成します。この参照は、関連するブランチやタグが削除された後でも作成されます。そのため、環境の自動停止や、ブランチ削除後にパイプラインを実行するマージトレインなどの機能で役に立ちます。

パイプラインの確認

プロジェクトのBuild > Pipelinesページで、現在および過去のパイプラインを確認できます。また、パイプラインタブに移動することで、マージリクエストのパイプラインにアクセスできます。

Pipelines index page

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

指定したブランチの最終コミットの最新パイプラインへのリンクは、/project/-/pipelines/[branch]/latest にあります。また、/project/-/pipelines/latest は、プロジェクトのデフォルトブランチの最終コミットの最新パイプラインにリダイレクトします。

GitLab 13.0からは、パイプラインリストを次のようにフィルタリングできるようになりました。

GitLab 14.2から、パイプラインカラムをパイプラインIDまたはパイプラインIIDの表示に変更することができます。

VS Codeを使ってGitLab CI/CD設定を編集する場合、GitLab Workflow VS Codeエクステンションは 設定の検証や パイプラインステータスの表示に役立ちます。

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

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

パイプラインの標準オペレーション以外でパイプラインの結果(例えば、コードビルド)が必要な場合、このようにします。

パイプラインを手動で実行するには、以下手順のしたがって行います。

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. Build > Pipelinesを選択します。
  3. パイプラインの実行を選択します。
  4. Run for branch name or tagフィールドで、パイプラインを実行するブランチまたはタグを選択します。
  5. パイプラインの実行に必要なCI/CD 変数を入力します。特定の変数がフォームにプリフィルドされるように設定できます。
  6. パイプラインの実行を選択します。

パイプラインが設定通りにジョブを実行します。

手動パイプラインでの変数の事前入力

GitLab 13.7 で導入されました

descriptionvalue キーワードを使って、パイプラインレベル(グローバル)変数を定義し、手動でパイプラインを実行する際に事前に入力することができます。説明には、その変数が何に使われるのか、どのような値が許容されるのかといった情報を記述します。

ジョブレベルの変数はプリフィルドできません。

手動トリガーのパイプラインでは、Run pipelineページに、.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 がデフォルト値として事前に入力され、他のオプションについて説明するメッセージが表示されます。
note
既知のイシューのため、コンプライアンス・パイプラインを使用するプロジェクトでは、パイプラインを手動で実行するときに、事前に入力された変数が表示されないことがあります。このイシューを回避するには、コンプライアンス・パイプライン設定を変更します。

選択可能なプリフィルド変数値のリストの設定

  • GitLab 15.5 でrun_pipeline_graphql というフラグで導入されました。デフォルトでは無効です。
  • options キーワードはGitLab 15.7で導入れました。
  • 一般的にGitLab 15.7で利用可能。機能フラグrun_pipeline_graphql を削除しました。
  • バグにより変数リストが正しく入力されないことがありましたが、GitLab 15.9で解決されました。

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

使用例:

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

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

GitLab 12.5で導入されました

クエリ文字列を使ってパイプラインの実行ページに事前に入力することができます。例えば、.../pipelines/new?ref=my_branch&var[foo]=bar&file_var[file_foo]=file_bar というクエリ文字列はパイプラインの実行ページにあらかじめ入力されます:

  • Run forfield:my_branch.
  • 変数セクション:
    • Variable:
      • キーfoo
      • 値:bar
    • File:
      • キーfile_foo
      • 値:file_bar

pipelines/new URLのフォーマットは以下の通りです:

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

以下のパラメータがサポートされています。

  • refRun forフィールドに入力するブランチを指定します。
  • var Variable 変数を指定します。
  • file_var File 変数を指定します。

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

パイプラインへ手動アクションの追加

手動ジョブを使用すると、パイプラインを進める前に手動での作業を要求することができます。

パイプライングラフから直接実行できます。再生ボタンを選択するだけで、特定のジョブを実行できます。

例えば、パイプラインは自動的に開始されますが、本番環境へのデプロイには手動アクションが必要です。下の例では、production ステージに手動アクションのジョブがあります:

Pipelines example

ステージ内で複数の手動アクションを開始

GitLab 11.11で導入されました

このアクションを選択すると、個々の手動アクションがトリガーされ、更新されたステータスにリフレッシュされます。

この機能は、次の場合にのみ使用できます。

  • 少なくともDeveloperロールを持つユーザー。
  • ステージに手動アクションを含む場合。

パイプラインをスキップ

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

Git 2.10 以降を使っている場合は、ci.skip Git push オプションを ci.skip使うこともできます。pushci.skip オプションは ci.skipマージリクエストパイプラインをスキップしません。

パイプラインを削除

GitLab 12.7から導入されました

プロジェクトのオーナーロールを持つユーザーは、Build > Pipelinesでパイプラインを選択してPipeline Detailsページを表示し、Delete を選択することでパイプラインを削除できます。

Pipeline Delete

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

caution
パイプラインを削除すると、すべてのパイプラインキャッシュが失効し、ビルド、ログ、アーティファクト、トリガーなど、すぐに関連するすべてのオブジェクトが削除されます。このアクションは元に戻せません。

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

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

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

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

保護されているとマークされた変数には、保護されたブランチのパイプラインで実行されるジョブがアクセスできます。デプロイ資格情報やトークンのような機密情報へのアクセス権限を持っているユーザーにのみ、保護されたブランチへのマージ権限を割り当ててください。

保護されているとマークされたランナーは、保護されたブランチ上でのみジョブを実行できるため、信頼されていないコードが保護されたランナー上で実行されることを防ぎ、デプロイメントキーやその他のクレデンシャルに意図せずアクセスされることを防ぎます。保護されたRunner上で実行されることを意図したジョブが通常のRunnerを使用しないことを保証するには、それに応じてタグを付ける必要があります。

パイプラインのセキュリティに関するその他の推奨事項については、デプロイの安全性のページをレビューしてください。

アップストリームプロジェクトが再構築されたときにパイプラインをトリガーする方法

GitLab 12.8で導入されました

別のプロジェクトの新しいタグのパイプラインが終了するたびに、プロジェクトのパイプラインをトリガーすることができます。

前提条件:

  • アップストリームプロジェクトが公開されていること。
  • ユーザーはアップストリームプロジェクトの開発者ロールを持っている必要があります。

アップストリームプロジェクトが再構築されたときにパイプラインをトリガするため:

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. Settings > CI/CDを選択します。
  3. パイプラインサブスクリプションを展開します。
  4. プロジェクトの追加]を選択します。
  5. 購読したいプロジェクトを<namespace>/<project> の形式で入力します。例えば、プロジェクトがhttps://gitlab.com/gitlab-org/gitlab の場合、gitlab-org/gitlabを使用します。
  6. Subscribe を選択します。

サブスクライブしたプロジェクトの新しいタグに対して正常に完了したパイプラインは、現在のプロジェクトのデフォルトブランチのパイプラインをトリガーします。アップストリームプロジェクトとダウンストリームプロジェクトの両方で、アップストリームパイプラインのサブスクリプションの最大数はデフォルトで2です。セルフマネージドインスタンスでは、管理者がこの上限を変更できます。

パイプラインの実行時間の計算方法

指定されたパイプラインの総実行時間は、リトライとペンディング(キューイング)時間を除いたものです。

各ジョブはPeriod で表されます:

  • Period#first (ジョブの開始時)。
  • Period#last (ジョブ終了時)。

簡単な例。

  • A (1, 3)
  • B (2, 4)
  • C (6, 7)

上記例は、以下のように解釈されます。

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

視覚的に表すと、以下のようになります。

0  1  2  3  4  5  6  7
   AAAAAAA
      BBBBBBB
                  CCCC

A/B/Cの和は(1,4)と(6,7)なので、総実行時間は以下のようになります。

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

パイプラインの可視化

パイプラインは、多くの順次実行ジョブや並列実行ジョブを含む複雑な構造になりえます。

パイプラインの流れをよりわかりやすくするために、GitLabにはパイプラインとその状態を見るためのパイプライングラフがあります。

パイプライングラフは、グラフにアクセスするページによって、大きなグラフで表示されたり、ミニチュアで表示されたりします。

GitLabはパイプライングラフのステージ名を大文字にします。

パイプライングラフをフル表示

GitLab 13.11で導入された可視化の改善。

パイプラインの詳細ページでは、パイプライン内の全てのジョブの完全なパイプライングラフが表示されます。

ジョブをグループ化できます:

  • 同じステージのジョブを同じ列に並べます:

    jobs grouped by stage

  • ジョブの依存関係needs の依存関係に基づいてジョブを並べます。

マルチプロジェクトパイプライングラフは、すべてのプロジェクト間依存関係を含むパイプライン全体を視覚化するのに役立ちます。

ステージに100以上のジョブが含まれる場合、最初の100ジョブのみがパイプライングラフに表示されます。残りのジョブは通常通り実行されます。ジョブを見るには

  • パイプラインを選択すると、パイプライン詳細ページの右側にジョブが表示されます。
  • 左側のサイドバーで、[Build] > [Jobs]を選択します。

パイプライングラフでジョブの依存関係を表示します。

パイプライングラフでジョブをneeds の依存関係に基づいて並べるには、Group jobs byセクションでJob dependenciesを選択してください。このオプションは、needs ジョブ依存関係を持つジョブが 3 つ以上あるパイプラインで利用できます。

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

例えば、test-job1 は最初のカラムのジョブにのみ依存するので、左から2番目のカラムに表示されます。deploy-job1 は最初のカラムと2番目のカラムの両方のジョブに依存するので、3番目のカラムに表示されます:

jobs grouped by needs dependency

ジョブ間のneeds 関係を表示する行を追加するには、依存関係の表示トグルを選択してください。これらの行はニーズの可視化と似ています:

jobs grouped by needs dependency with lines displayed

ジョブの完全な依存関係ツリー (needs ) を表示するには、そのジョブの上にカーソルを置いてください:

single job dependency tree highlighted

パイプラインミニグラフ

パイプライン・ミニ・グラフは場所をとらず、すべてのジョブがパスしたか、何か失敗したかを一目で知ることができます。パイプライン・ミニグラフは、次のページで見ることができます:

パイプラインのミニグラフでは、1つのコミットに関連するすべてのジョブと、パイプラインの各ステージの最終結果を表示できます。これにより、何が失敗したのかを素早く確認し、修正できます。

パイプラインのミニグラフはステージごとのジョブのみを表示します。

パイプラインミニグラフのステージは拡張可能です。各ステージにマウスカーソルを合わせると名前とステータスが表示され、ステージを選択するとジョブリストが展開されます。

ミニグラフ展開したミニグラフ
Pipelines mini graphPipelines mini graph extended

パイプラインの成功と実行時間のチャート

パイプライン分析はCI/CD Analyticsページでご覧いただけます。

パイプラインバッジ

パイプラインステータスとテストカバレッジレポートバッジは、プロジェクトごとに利用と設定が可能です。プロジェクトへのパイプラインバッジの追加については、パイプラインバッジを参照してください。

パイプラインAPI

GitLabはAPIエンドポイントを提供しています。