プル要求パイプライン

プルリクエストパイプラインは、指定されたアプリケーションリポジトリのプルリクエストに対して、一連のコンプライアンス状況チェックを実行します。

プル要求をマスター・ブランチにマージしようとすると、コンプライアンス状況検査に失格したことが原因でブロックされる場合があります。マスター・ブランチに対するプル要求を開くか更新すると、プル要求パイプラインの実行がトリガーされます。「カスタムスクリプト」では、パイプラインやテストに対して独自の設定を実行することができます。

ステージとタスク

次の表は、PRパイプラインで実行されるタスクの一覧です。さらに、この表には、以下の各ステージの概要も示されています。

タスクまたはステージ: これは、 .pipeline-config.yaml 構成ファイル内で定義されているステージの名前を参照します。
簡略説明: ステージの実行中に実行されたアクションについて簡潔に説明します。
許容されるカスタマイズ: これは、 .pipeline-config.yaml ファイルにカスタム・スクリプトを挿入することによって、ステージのデフォルトの動作を変更または置換する柔軟性がユーザーにあるかどうかを示します。
Default Reference Implementation: これは、DevSecOps パイプラインに、ステージ用の定義済みまたはデフォルトの実装が付属しているかどうかを示します。 unit-tests や setup のような特定のステージでは、DevSecOps パイプラインはすぐに使える実装を提供していません。代わりに、ユーザーは、アプリケーションの要件に合わせて調整されたカスタム・スクリプトまたはコードを提供する必要があります。
エビデンス・コレクション: ステージが標準エビデンスの収集を実行するかどうかを示します。 DevSecOps Pipeline がステージの参照実装を提供する場合、証拠収集はすぐに実行されます。ただし、 「ユーザー」 がこれらの事前定義ステージを変更または置換することを選択した場合は、カスタム実装に適切なエビデンス・コレクションが含まれていることを確認する必要があります。 DevSecOps パイプラインがすぐに使える実装を提供しないステージでは、同じ責任がユーザーにあり、ユーザーが証拠収集を行う必要があります。この列は、エビデンス収集の実行を担当するエンティティー (ユーザー/パイプライン) を示します。
スキップ可能 (バージョン> = v10に適用可能): これは、 .pipeline-config.yamlでスキップ・プロパティーを true に設定することによって、ユーザーがこのステージの実行をオプトアウトできるかどうかを示します。ただし、この機能を使用する場合、特に証拠を収集するために設計されたステージでは注意が必要です。このようなステージをスキップすると、ビルドに不可欠な証拠が欠落する可能性があります。

パイプライン順序
タスクまたはステージ	簡略説明	`.pipeline-config.yaml` で許容されるカスタマイズ	デフォルトの参照実装	証拠収集要件	許容されるスキップ
`start`	パイプライン環境をセットアップします。	いいえ	はい	NA	いいえ
`setup`	ビルドおよびテスト環境をセットアップします。	はい	いいえ	該当なし	いいえ
`detect-secrets`	アプリケーション・コードに対して検出シークレット・スキャンを実行します。	はい	はい	NA	いいえ
`unit-tests`	アプリ・コードに対して単体テストおよびアプリ・テストを実行します。	はい	いいえ	NA	はい
`compliance-checks`	アプリ・リポジトリーに対して Code Risk Analyzer スキャンおよびその他のコンプライアンス・チェックを実行します。	はい	はい	NA	はい
`finish`	パイプラインの状況を統合します。	はい	はい	NA	はい

.pipeline-config.yaml ファイルを使用してステージをカスタマイズする方法について詳しくは、カスタム・スクリプトおよびパイプラインのパラメーターを参照してください。

シークレット・スキャンの検出

IBM Detect Secrets ツールは、アプリ・コード内でシークレットが可視状態になっている場所を特定します。スキャン用にリポジトリーをセットアップする方法について詳しくは、ここを参照してください。

コンプライアンス検査でのスキャンと検査

スキャンまたは検査	説明
Code Risk Analyzer による脆弱点スキャン	アプリのパッケージ依存関係、コンテナーの基本イメージ、オペレーティング・システム・パッケージのすべてについて脆弱性を検出します。 Code Risk Analyzer ツールを使用します。
Code Risk Analyzer による CIS 検査	Kubernetes デプロイメント・マニフェストに対して構成チェックを実行します。 Code Risk Analyzer ツールを使用します。
Code Risk Analyzer による部品構成表 (BOM) 検査	すべての依存関係のペディグリーを取り込む、指定されたリポジトリーの BOM です。この BOM はさまざまな細分度で収集されます。例えば、BOM は、ビルドで使用される基本イメージのリスト、基本イメージにあるパッケージのリスト、基本イメージの上にインストールされるアプリ・パッケージのリストを収集します。 BOM は分析結果のグラウンド・トゥルースとして機能します。ポリシー・ゲートを適用するために使用できることもあります。 Code Risk Analyzer ツールを使用します。

| リポジトリ・コンプライアンス・チェック｜ブランチ保護の設定が正しいかチェックします。|

これらのスクリプトは、パイプラインが認識するすべてのアプリ・リポジトリーに対して実行されます。これらのスキャンにリポジトリーを追加するには、セットアップ・ステージで利用できる pipelinectl インターフェースを使用してください。

ユーザー・スクリプトの各ステージからの予想される出力について詳しくは、カスタム・スクリプトを参照してください。

タスク・ジョブ

コンプライアンス・スキャンとチェック
タスク・ジョブ	説明
`code-pr-start`	アプリ・リポジトリーと DevSecOps リポジトリーを複製し、Git Repos and Issue Tracking リポジトリーに対する状況検査のために初期状態として保留状態を設定します。
`code-setup`	ユーザーが独自のパイプライン・セットアップを実行できる、ユーザー定義のセットアップ・カスタム・スクリプトを指定するためのプレースホルダー。
`code-detect-secrets`	シークレット検出スキャンを実行して、アプリ・コード内のシークレットが表示される場所を識別します。
`code-unit-tests`	ユーザーが独自のテストを実行できる、ユーザー定義のテスト・カスタム・スクリプトを指定するためのプレースホルダー。
`code-pr-finish`	必要なコンプライアンス検査をすべて実行し、結果をコメントとしてプル要求に追加し、結果を Git Repos and Issue Tracking リポジトリーに設定します。

PR/MRの変更をパイプライン設定レポに使用する

PRパイプラインがPR/MRからの設定ファイル/スクリプトの変更を考慮する場合、設定レポとブランチは空でなければなりません：

env変数 one-pipeline-repo 、 one-pipeline-config-repo 、 pipeline-config-repo が空であるか、env変数に指定されていない
env変数 one-pipeline-config-branch と pipeline-config-branch が空であるか、env変数に指定されていない。

問題のあるプル要求のマージ

管理者権限を使用すると、状況検査に失格したプル要求をリポジトリーにマージできます。ただし、そのようなプル要求では、失敗したタスクのエビデンスに failure 結果が記録されます。この結果は、エビデンスの要約と変更要求の記述に含まれている。

PRパイプラインでの証拠収集を可能にする

PRパイプラインは、問題管理とともに証拠収集をサポートする。デフォルトでは、PRパイプラインは証拠を収集したり、issueをオープンしたりしませんが、ユーザーはこの機能にオプトインすることができます。証拠収集と問題管理を有効にするには、環境変数 collect-evidence-in-pr を以下の列挙型のいずれかに設定します：

none: (デフォルト) collect-evidence-in-pr から none に設定し、PRパイプラインでの証拠収集を防ぎます。
all: collect-evidence-in-pr を all に設定すると、PRパイプラインのステータスに関係なく、すべての証拠を集めることができます。 collect-evidence スクリプトに従って、issueが開かれたり、更新されたり、閉じられたりします。
success: collect-evidence-in-pr を success に設定すると、PRパイプライン全体が正常に実行された場合にのみ証拠を収集することができます。 PRパイプラインが失敗した場合、エビデンスは収集されず、エビデンスロッカーに公開されず、問題管理は行われない。

注意：PRパイプラインは一般的にかなり頻繁に実行されるため、collect-evidence-in-pr のモードを正しく選択することで、不必要な証拠収集を避けることができます。パイプラインが故障した場合の証拠収集を防ぐため、success モードを開発段階や故障が予想される場合に選択することが推奨される。

PR パイプラインが Async パイプラインをトリガーする場合、collect-evidence-in-pr を success モードに設定することはサポートされません。 PRパイプラインが非同期パイプラインをトリガーする場合は、証拠を収集するために collect-evidence-in-pr を all に設定します。

注記: アプリケーションリポジトリが GitLab リポジトリであり、貢献されるマージリクエスト (MR) がフォークされたリポジトリからのものである場合、ユーザーはソースリポジトリとターゲットリポジトリ git-token の両方にアクセス権を持つ環境変数の値を提供し、マージリクエストに適切なステータスを設定する必要があります。つまり、Gitトークンは、ベースリポジトリとフォークされたリポジトリの両方で貢献しているユーザーに属している必要があり、そのトークンにはコミットの状態を設定する権限が与えられている必要があります。

広報におけるCVE浮上

PR が作成され、PR パイプラインによって脆弱性が発見されると、パイプラインは深刻度、cve 識別子、パッケージとその説明、修正プログラムがあればそのコメントといった脆弱性情報を追加します。これにより、ユーザーはパイプラインのログを調べる代わりに、PRで修正される脆弱性を素早くチェックすることができる。

オプトインフラグ opt-in-pr-updates は、PRパイプラインでこの機能を有効/無効にするために利用できます。これはデフォルトで有効になっています。

Github Merge QueueのPRを処理するPRパイプラインのセットアップ

マージキューはGithubの機能で、忙しいブランチへのプルリクエストのマージを自動化し、互換性のない変更によってブランチが壊れないようにすることで、ベロシティを向上させるのに役立ちます。 Github Merge Queueの設定と使い方についてはこちらをご覧ください。

Merge Queueの目的はベロシティの向上ですが、特定の Git プルリクエストについては、プルリクエストのパイプラインが2回実行されることを考慮する必要があります。まず「標準」のプルリクエストが実行されます。完了したら、Merge Queue PR を実行してください。

Git トリガーを新規作成する

新しい Git トリガーを作成するか、既存のものを複製します。すべてのデフォルト設定を維持し、以下のプロパティのみを上書きする：

Name Merge Queueのコンテキストを反映したトリガー名を持つことが望ましいです： PR - Merge Queue
EventListener セレクト pr-listener-merge-queue
Trigger on セレクト CEL filter
- CEL filter 入る body.action == 'checks_requested'

マージキューPRは、元のPRがマージキューに追加されたときに動的に作成されるエフェメラルブランチを使用します。その結果、対応する Git イベントペイロード（プルリクエストパイプラインをトリガーするもの）には、PR URL または HTML URL に関する情報が一切含まれていません。

マージキューコンテキストでは無関係です。対応するテキストプロパティを追加して、以下の DevSecOps 機能を無効にする必要があります：

skip-merge-pr-to-base true （デフォルトはfalse）に設定する
opt-in-pr-updates 0 （デフォルト1）に設定する

トリガーを保存する。

マージキュートリガーのテスト

アプリケーションのソースコードリポジトリのメインブランチに対して新しいPull Requestを作成します。
DevSecOps PRパイプラインがトリガーされる
PRページで、 Merge when ready をクリックし、 Attempt merge when ready をクリックします。これにより、「標準」PRが完了すると、PRはマージキューに enqueue。
標準」 DevSecOps PRが正常に完了するまで待つ
観察：PRパイプラインが完了すると、PRはマージキューに追加され、マージキューのPRがトリガーされる：
- マージキューPRの完了を待つ
- 成功すれば、PRは次のようなコメントとともにマージされる。 Merged via the queue into main with commit abcdefg
- 成功しなかった場合（例：コンプライアンスチェックが失敗した場合）、PRは自動マージされず、マージキューから削除されます。

PRペイロードの概要

ペイロード

ペイロードは、イベントやリクエストの一部として送信される、構造化されたデータブロック（通常はJSONフォーマット）を表すために使用される一般的な用語である。ペイロードは、ウェブフック、API、自動化システムで一般的に使用され、機械可読形式で関連情報を伝達する。

例えば、ビルドのメタデータ、ユーザーのアクティビティ、issueの更新、この場合はプルリクエストの詳細などである。

PRペイロード

#CD-DevSecOps-PR-ペイロード

PRペイロードは、プルリクエスト（PR）に関するメタデータとコンテキスト情報をカプセル化したペイロードの特定のインスタンスである。これは、プルリクエストイベントが発生したときに生成され、そのPRに関連する主要な属性への構造化されたアクセスを提供します。

このペイロードには、以下のような幅広いデータが含まれている：

PRタイトルと説明文
著者と査読者
ソース（ヘッド）ブランチとターゲット（ベース）ブランチ
コミット履歴とSHAリファレンス
リポジトリーの詳細
タイムスタンプ、ラベル、ステータスなど

ペイロード全体には広範な情報が含まれているが、現在は特定のフィールドのサブセットのみが抽出され、パイプライン、スクリプト、設定ファイルで使用するための環境変数として公開されている。

PRペイロードから抽出された環境プロパティ

現在、以下の環境変数がPRペイロードから派生し、積極的に使用されている：

変数名	説明
`head-branch`	PRのソースブランチ（マージ元のブランチ）
`head-sha`	head ブランチの最新コミットのコミット SHA
`head-repo`	PRの発信元リポジトリ
`base-branch`	PR のターゲットブランチ (マージ先のブランチ)
`base-repo`	ベースリポジトリへの完全なリファレンス
`base-repo-name`	ベースリポジトリの名前
`base-repo-owner`	ベースリポジトリの所有者（ユーザーまたは組織
`commit-timestamp`	PR の最新コミットのタイムスタンプ
`pr-url`	プルリクエストの API URL
`pr-html-url`	プルリクエストのウェブ（HTML） URL
`pr-title`	プルリクエストのタイトル
`action`	PR状況
`base_ref`	PR対象ブランチ

これらの値は環境変数として注入され、自動化されたワークフローでの実行中のアクセスを簡素化する。

PRペイロードには、上記以外にも多くのフィールドが含まれる。しかし、現在、運用目的で活用されているのは、抽出されたサブセットのみである。必要であれば、高度な使用例や将来の拡張のために、完全なペイロードへのアクセスを提供することができる。