CI/CDパイプライン
パイプラインは、継続的なインテグレーション、デリバリ、デプロイメントのトップレベルのコンポーネントです。
パイプラインの構成は、以下のとおりです。
- ジョブとは、何をするかを定義するものです。例えば、コードをコンパイルしたり、テストしたりするジョブがあげられます。
- ステージとは、ジョブを実行するタイミングを定義するものです。例えば、テストを実行するステージは、コードをコンパイルするステージの後に実行するなどです。
ジョブはRunner によって実行されます。同じステージの複数のジョブは、十分な数の同時実行ランナーがいれば並行して実行されます。
ステージ内のすべてのジョブが成功すれば、パイプラインは次のステージに進みます。
あるステージのジョブがどこかで失敗すると、一般的に次のステージは実行されず、パイプラインはそこで終了します。
通常パイプラインは自動的に実行され、一度作成されたパイプラインへ介入する必要はありません。しかし、手動でパイプラインとやり取りする場合もあります。
典型的なパイプラインは、以下の順序で実行される4つのステージで構成されています。
-
buildcompileというジョブのステージ。 -
test1とtest2という2つのジョブを持つtestステージ。 -
stagingdeploy-to-stageというジョブのステージ。 -
productiondeploy-to-prodというジョブのステージ。
パイプラインの種類
パイプラインは様々な方法で設定できます。
- ベーシックパイプラインは、各ステージのすべてを同時に実行した後、次のステージに進みます。
- 有効非巡回グラフパイプライン(DAG) パイプラインはジョブ間の関係に基づいており、基本パイプラインよりも高速に実行できます。
- マージリクエストパイプラインはマージリクエストに対してのみ実行されます (すべてのコミットに対して実行されるわけではありません)。
- マージ結果パイプラインはマージリクエストパイプラインで、ソースブランチの変更がターゲットブランチにマージされたかのように動作します。
- マージトレインはマージ結果パイプラインを使用して、マージを次々にキューに入れます。
- 親子パイプラインは、複雑なパイプラインを1つの親パイプラインに分解し、複数の子サブパイプラインをトリガーできるようにします。このパイプラインアーキテクチャは、Mono-Reposによく使用されます。
- マルチプロジェクトパイプライン、は異なるプロジェクトのパイプラインを一緒に結合します。
パイプラインの設定
パイプラインとそれを構成するジョブおよびステージは、各プロジェクトのCI/CDパイプライン設定ファイルに定義されています。
CIパイプラインファイルの設定オプションの一覧は、GitLab CI/CDパイプライン設定リファレンスを参照してください。
GitLab UIから、パイプラインの特定部分を設定も可能です。
- 各プロジェクトのパイプライン設定。
- パイプラインスケジュール。
- カスタムCI/CD変数。
ランナーの参照仕様
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ページで、現在および過去のパイプラインを確認できます。また、パイプラインタブに移動することで、マージリクエストのパイプラインにアクセスできます。
パイプラインを選択するとパイプライン詳細ページが開き、そのパイプラインで実行されたジョブが表示されます。ここから、実行中のパイプラインをキャンセルしたり、失敗したパイプラインのジョブを再試行したり、パイプラインを削除したりできます。
指定したブランチの最終コミットの最新パイプラインへのリンクは、/project/-/pipelines/[branch]/latest にあります。また、/project/-/pipelines/latest は、プロジェクトのデフォルトブランチの最終コミットの最新パイプラインにリダイレクトします。
GitLab 13.0からは、パイプラインリストを次のようにフィルタリングできるようになりました。
- Trigger author
- Branch name
- ステータス(GitLab 13.1 以降)
- タグ(GitLab 13.1 以降)
- ソース(GitLab 14.3 以降)
GitLab 14.2から、パイプラインカラムをパイプラインIDまたはパイプラインIIDの表示に変更することができます。
VS Codeを使ってGitLab CI/CD設定を編集する場合、GitLab Workflow VS Codeエクステンションは 設定の検証や パイプラインステータスの表示に役立ちます。
パイプラインを手動で実行
パイプラインは、事前に定義された変数または手動で指定する変数を使用して、手動で実行できます。
パイプラインの標準オペレーション以外でパイプラインの結果(例えば、コードビルド)が必要な場合、このようにします。
パイプラインを手動で実行するには、以下手順のしたがって行います。
- 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
- Build > Pipelinesを選択します。
- パイプラインの実行を選択します。
- Run for branch name or tagフィールドで、パイプラインを実行するブランチまたはタグを選択します。
- パイプラインの実行に必要なCI/CD 変数を入力します。特定の変数がフォームにプリフィルドされるように設定できます。
- パイプラインの実行を選択します。
パイプラインが設定通りにジョブを実行します。
手動パイプラインでの変数の事前入力
GitLab 13.7 で導入されました。
description とvalue キーワードを使って、パイプラインレベル（グローバル）変数を定義し、手動でパイプラインを実行する際に事前に入力することができます。説明には、その変数が何に使われるのか、どのような値が許容されるのかといった情報を記述します。
ジョブレベルの変数はプリフィルドできません。
手動トリガーのパイプラインでは、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がデフォルト値として事前に入力され、他のオプションについて説明するメッセージが表示されます。
選択可能なプリフィルド変数値のリストの設定
パイプラインを手動で実行する際にユーザーが選択できる 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
- キー
- Variable：
pipelines/new URLのフォーマットは以下の通りです：
.../pipelines/new?ref=<branch>&var[<variable_key>]=<value>&file_var[<file_key>]=<value>
以下のパラメータがサポートされています。
-
refRun forフィールドに入力するブランチを指定します。 -
varVariable変数を指定します。 -
file_varFile変数を指定します。
各var またはfile_var には、キーと値が必要です。
パイプラインへ手動アクションの追加
手動ジョブを使用すると、パイプラインを進める前に手動での作業を要求することができます。
パイプライングラフから直接実行できます。再生ボタンを選択するだけで、特定のジョブを実行できます。
例えば、パイプラインは自動的に開始されますが、本番環境へのデプロイには手動アクションが必要です。下の例では、production ステージに手動アクションのジョブがあります：
ステージ内で複数の手動アクションを開始
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 を選択することでパイプラインを削除できます。
パイプラインを削除しても、その子パイプラインは自動的に削除されません。詳細は関連イシューを参照してください。
保護ブランチのパイプラインセキュリティ
パイプラインが保護ブランチ上で実行される際には、厳格なセキュリティモデルが適用されます。
ユーザーが特定のブランチへのマージやプッシュを許可されている場合、保護されたブランチでは以下のアクションが許可されます：
- 手動パイプラインを実行する（Web UIまたはパイプラインAPIを使用）。
- スケジュールされたパイプラインを実行する。
- トリガーを使用してパイプラインを実行する。
- オンデマンドDASTスキャンの実行
- 既存のパイプラインの手動アクションをトリガーする。
- 既存のジョブを再試行またはキャンセルする（Web UIまたはパイプラインAPIを使用）。
保護されているとマークされた変数には、保護されたブランチのパイプラインで実行されるジョブがアクセスできます。デプロイ資格情報やトークンのような機密情報へのアクセス権限を持っているユーザーにのみ、保護されたブランチへのマージ権限を割り当ててください。
保護されているとマークされたランナーは、保護されたブランチ上でのみジョブを実行できるため、信頼されていないコードが保護されたランナー上で実行されることを防ぎ、デプロイメントキーやその他のクレデンシャルに意図せずアクセスされることを防ぎます。保護されたRunner上で実行されることを意図したジョブが通常のRunnerを使用しないことを保証するには、それに応じてタグを付ける必要があります。
パイプラインのセキュリティに関するその他の推奨事項については、デプロイの安全性のページをレビューしてください。
アップストリームプロジェクトが再構築されたときにパイプラインをトリガーする方法
GitLab 12.8で導入されました。
別のプロジェクトの新しいタグのパイプラインが終了するたびに、プロジェクトのパイプラインをトリガーすることができます。
前提条件：
- アップストリームプロジェクトが公開されていること。
- ユーザーはアップストリームプロジェクトの開発者ロールを持っている必要があります。
アップストリームプロジェクトが再構築されたときにパイプラインをトリガするため：
- 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
- Settings > CI/CDを選択します。
- パイプラインサブスクリプションを展開します。
- プロジェクトの追加]を選択します。
- 購読したいプロジェクトを
<namespace>/<project>の形式で入力します。例えば、プロジェクトがhttps://gitlab.com/gitlab-org/gitlabの場合、gitlab-org/gitlabを使用します。 - 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で導入された可視化の改善。
パイプラインの詳細ページでは、パイプライン内の全てのジョブの完全なパイプライングラフが表示されます。
ジョブをグループ化できます：
マルチプロジェクトパイプライングラフは、すべてのプロジェクト間依存関係を含むパイプライン全体を視覚化するのに役立ちます。
ステージに100以上のジョブが含まれる場合、最初の100ジョブのみがパイプライングラフに表示されます。残りのジョブは通常通り実行されます。ジョブを見るには
- パイプラインを選択すると、パイプライン詳細ページの右側にジョブが表示されます。
- 左側のサイドバーで、[Build] > [Jobs]を選択します。
パイプライングラフでジョブの依存関係を表示します。
パイプライングラフでジョブをneeds の依存関係に基づいて並べるには、Group jobs byセクションでJob dependenciesを選択してください。このオプションは、needs ジョブ依存関係を持つジョブが 3 つ以上あるパイプラインで利用できます。
一番左の列のジョブが最初に実行され、それらに依存するジョブは次の列にグループ化されます。
例えば、test-job1 は最初のカラムのジョブにのみ依存するので、左から2番目のカラムに表示されます。deploy-job1 は最初のカラムと2番目のカラムの両方のジョブに依存するので、3番目のカラムに表示されます：
ジョブ間のneeds 関係を表示する行を追加するには、依存関係の表示トグルを選択してください。これらの行はニーズの可視化と似ています：
ジョブの完全な依存関係ツリー (needs ) を表示するには、そのジョブの上にカーソルを置いてください：
パイプラインミニグラフ
パイプライン・ミニ・グラフは場所をとらず、すべてのジョブがパスしたか、何か失敗したかを一目で知ることができます。パイプライン・ミニグラフは、次のページで見ることができます：
- パイプラインの一覧画面。
- コミットの詳細画面。
- マージリクエストの詳細画面。
- GitLab 14.5以降のパイプラインエディター。
パイプラインのミニグラフでは、1つのコミットに関連するすべてのジョブと、パイプラインの各ステージの最終結果を表示できます。これにより、何が失敗したのかを素早く確認し、修正できます。
パイプラインのミニグラフはステージごとのジョブのみを表示します。
パイプラインミニグラフのステージは拡張可能です。各ステージにマウスカーソルを合わせると名前とステータスが表示され、ステージを選択するとジョブリストが展開されます。
| ミニグラフ | 展開したミニグラフ |
|---|---|
 |  |
パイプラインの成功と実行時間のチャート
パイプライン分析はCI/CD Analyticsページでご覧いただけます。
パイプラインバッジ
パイプラインステータスとテストカバレッジレポートバッジは、プロジェクトごとに利用と設定が可能です。プロジェクトへのパイプラインバッジの追加については、パイプラインバッジを参照してください。
パイプラインAPI
GitLabはAPIエンドポイントを提供しています。
- 基本的な機能の詳細については、パイプラインAPIを参照してください。
- パイプラインスケジュール管理の詳細については、パイプラインスケジュールAPIを参照してください。
- トリガーパイプライン実行の詳細については、以下を参照してください。