取回要求管線

取回要求管線會對指定應用程式儲存庫的取回要求執行一組相符性狀態檢查。

由於相符性狀態檢查失敗，可能已封鎖將取回要求合併至主要分支的嘗試。 針對主要分支開啟或更新取回要求會觸發執行取回要求管線。 您可以在 自訂 Script 中執行您自己的管線和測試設定。

階段和作業

下表列出 PR 管道中執行的任務。 此外，此表格還提供下列每一個階段的概觀:

  • 作業或階段: 這是指 .pipeline-config.yaml 配置檔內所定義的階段名稱。

  • 簡要說明: 這會提供在階段執行期間所執行之動作的簡要說明。

  • 允許自訂: 這指出使用者是否有彈性在 .pipeline-config.yaml 檔中插入自訂 Script 來修改或取代階段的預設行為。

  • 預設參考實現：這表明是否DevSecOps管道帶有階段的預定義或預設實作。 值得注意的是，對於某些階段，例如 unit-tests 或者 setup，這DevSecOpspipeline 不提供任何開箱即用的實作。 相反地，使用者必須提供自訂 Script 或自訂程式碼，以符合其應用程式的需求。

  • 證明收集: 這指出階段是否執行標準證明收集。 什麼時候DevSecOps管道為階段提供參考實現，證據收集是開箱即用的。 不過，如果 使用者 選擇修改或取代這些預先定義的階段，則必須確保其自訂實作包括適當的證明集合。 在以下階段，使用者承擔同樣的責任：DevSecOpspipeline 不提供開箱即用的實現，因此需要他們執行證據收集。 該直欄指出負責執行證明收集的實體 (使用者/管線)。

  • 跳過允許 (適用於版本> = v10): 這指出使用者是否可以在 .pipeline-config.yaml中將 skip 內容設為 true，以拒絕執行此階段。 不過，在使用此特性時，尤其對於設計用於收集證明的階段，建議注意。 跳過這類階段可能會導致遺漏建置的必要證明。

管線訂單
作業或階段 簡短說明 在 .pipeline-config.yaml 中允許自訂 預設參照實作 證明集合需求 跳過允許
start 設定管線環境。 否 是 NA 否
setup 設定建置和測試環境。 是 否 NA 否
detect-secrets 在應用程式碼上執行偵測密鑰掃描。 是 是 NA 否
unit-tests 對應用程式碼執行單元測試及應用程式測試。 是 否 NA 是
compliance-checks 在應用程式儲存庫上執行 Code Risk Analyzer 掃描及其他相符性檢查。 是 是 NA 是
finish 合併管線狀態。 是 是 NA 是

如需如何使用 .pipeline-config.yaml 檔案來自訂階段的相關資訊，請參閱 自訂 Script 及 管線參數。

偵測密鑰掃描

IBM Detect Secrets 工具可識別在應用程式碼中可見密鑰的位置。 如需為掃描設定儲存庫的相關資訊，請參閱 這裡。

掃描並移入相符性檢查

掃描或檢查 說明
Code Risk Analyzer 漏洞掃描 尋找所有應用程式套件相依關係、容器基本映像檔及作業系統套件的漏洞。 使用 Code Risk Analyzer 工具。
Code Risk Analyzer CIS 檢查 在 Kubernetes 部署資訊清單上執行 配置檢查。 使用 Code Risk Analyzer 工具。
Code Risk Analyzer 物料清單 (BOM) 檢查 所指定儲存庫的 BOM，用於擷取所有相依關係的 pedigree。 這個 BOM 會以不同的粒度收集。 例如，BOM 會擷取建置中使用的基本映像檔清單、基本映像檔中的套件清單，以及在基本映像檔上安裝的應用程式套件清單。 BOM 充當分析結果的基準，並可能用來施行原則閘道。 使用 Code Risk Analyzer 工具。

| 儲存庫符合性檢查 | 檢查分支保護設定是否正確。|

這些 Script 會在管線知道的所有應用程式儲存庫上執行。 若要將儲存庫新增至這些掃描，請使用設定階段中提供的 pipelinectl 介面。

如需使用者 Script 階段預期輸出的相關資訊，請參閱 自訂 Script。

作業工作

合規性掃描和檢查
作業工作 說明
code-pr-start 克隆應用程式和DevSecOpsrepos，並設定狀態檢查的初始掛起狀態Git Repos and Issue Tracking回購協議。
code-setup 使用者定義設定自訂 Script 的位置保留元，使用者可以在其中完成其管線設定。
code-detect-secrets 執行偵測密鑰掃描，以識別在應用程式碼中可見密鑰的位置。
code-unit-tests 使用者定義測試自訂 Script 的位置保留元，使用者可以在其中執行自己的測試。
code-pr-finish 執行所有必要的相符性檢查，將結果註解至取回要求，並在 Git Repos and Issue Tracking 儲存庫上設定其結果。

將 PR/MR 變更用於管道配置 repo

如果 PR 管道應該考慮來自 PR/MR 的 config 檔案/指令碼變更，那麼 config repo 和分支應該是空的，可以如下設定：

  • 環境變數 one-pipeline-repo, one-pipeline-config-repo 和 pipeline-config-repo 為空或未在環境變數中指定
  • env 變數 one-pipeline-config-branch 和 pipeline-config-branch 為空或未在 env 變數中指定。

合併有問題的取回要求

您可以使用管理者權限，將狀態檢查失敗的取回要求合併至儲存庫。 不過，這些取回要求會登錄 failure，以產生其失敗作業的證明。 此結果包含在證據摘要和變更要求說明中。

在公關管道中啟用證據收集

PR 管道支持證據收集和問題管理。 預設情況下，PR 管道不會收集證據或開啟任何問題，但使用者可以選擇使用此功能。 為了啟用證據收集和問題管理，請設定環境變量 collect-evidence-in-pr 作為以下枚舉之一：

  • none：（預設）設定 collect-evidence-in-pr 到 none，防止公關管道中的證據蒐集。
  • all：放 collect-evidence-in-pr 到 all 收集所有證據，無論公關管道的狀態如何。 問題將根據以下內容開啟、更新或關閉 collect-evidence 腳本。
  • success：放 collect-evidence-in-pr 到 success 只有在整個 PR 管道成功運作時才收集證據。 如果 PR 管道失敗，則不會收集證據或將其發佈到證物櫃，並且不會進行問題管理。

注意：由於 PR 管道通常運作相當頻繁，因此請選擇正確的模式 collect-evidence-in-pr 將節省不必要的證據收集。 建議選擇 success 模式在開發階段或預計會發生故障的情況下，以防止在管道發生故障時收集證據。

如果 PR 管道觸發非同步管道，collect-evidence-in-pr 設定 success 不支援模式。 如果 PR 管道觸發非同步管道，請設定 collect-evidence-in-pr 到 all 以收集證據。

注意：若應用程式儲存庫為 GitLab 儲存庫，且提交的合併請求（MR）來自分支儲存庫，使用者需提供 env git-token 變數的值，該變數須同時具備原始儲存庫與目標儲存庫的存取權限，方能為合併請求設定正確狀態。 這表示 git 令牌需要屬於一個在基本套件庫和分叉套件庫都是貢獻者的使用者，而且該令牌有權限設定提交的狀態。

在公共關係中浮現 CVE

當 PR 管道建立並發現漏洞時，管道會加入漏洞資訊，例如嚴重性、cve 識別碼、套件及其描述，以及修補程式 (若有) 的註解。 這可讓使用者快速檢查 PR 中要修復的漏洞，而不必翻查管道日誌。

在 PR pipeline 中，可選擇啟用/停用此功能的標誌 opt-in-pr-updates。 此功能預設為啟用狀態。

設定 PR 管道以處理 Github 的合併佇列 PR

合併佇列 (Merge Queue) 是 Github 的一項功能，可透過自動將拉取請求合併到繁忙的分支，並確保分支不會因不相容的變更而遭到破壞，以協助提升速度。 更多關於設定和使用 Github Merge Queue 的資訊，請參閱 此處。

雖然「合併佇列」（Merge Queue）的目的是為了提高處理速度，但必須注意的是，對於任何一個「Git」拉取請求（PR），該 PR 流程將會執行兩次：首先執行「標準」的 PR。 完成後，請執行「合併佇列 PR」。

建立新的 Git 觸發器

建立新的 Git 觸發器或複製現有的觸發器。 保留所有預設設定，僅覆寫下列屬性：

  • Name：希望觸發器的名稱能反映合併佇列的上下文 - 例如：PR - Merge Queue
  • EventListener: 選擇 pr-listener-merge-queue
  • Trigger on: 選擇 CEL filter
    • CEL filter: 輸入 body.action == 'checks_requested'

合併佇列 PR 使用短暫分支 - 在原始 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- 這將 enqueue PR 到合併佇列，一旦「標準」PR 完成。
  • 等待「標準」DevSecOps PR 成功完成
  • 觀察：PR 管道完成後，PR 會加入合併佇列，並觸發合併佇列 PR：
    • 等待合併佇列 PR 完成
    • 如果成功，PR 將與註解合併，如 Merged via the queue into main with commit abcdefg
    • 如果不成功（例如：合規性檢查失敗），PR 將不會自動合併，並從合併佇列中移除。

PR 有效載荷概觀

有效負載

有效負載是一個通用術語，用來描述結構化的資料區塊，通常採用 JSON 格式，作為事件或請求的一部分進行傳輸。 Payload 常用於 webhook、API 和自動化系統，以機器可讀的形式傳達相關資訊。

根據上下文，有效負載可以代表各種不同的內容--例如，建置元資料、使用者活動、發行更新，或在本例中，拉取請求的詳細資訊。

PR 有效載荷

#cd-開發安全運維-PR-有效載荷

PR Payload 是一個特定的實例，它封裝了關於拉取請求 (PR) 的元資料和上下文資訊。 它會在拉取請求事件發生時產生，並提供與該 PR 相關的關鍵屬性的結構化存取。

此有效載荷包括範圍廣泛的資料，例如

  • PR 標題與描述
  • 作者和審查員
  • 來源 (頭) 和目標 (基) 分支
  • 提交歷史和 SHA 參考資料
  • 儲存庫詳細資料
  • 時間戳記、標籤、狀態等等

雖然完整的有效負載包含廣泛的資訊，但目前只有特定的欄位子集會被擷取並顯示為環境變數，供管道、腳本和組態檔使用。

從 PR Payload 擷取的環境屬性

下列環境變數目前來自 PR Payload 並積極使用：

變數名稱 說明
head-branch PR 的原始分支 (合併的分支)
head-sha 頭分支上最新提交的 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 Payload 除了上面列出的欄位外，還包含許多其他欄位。 不過，目前只有擷取的子集才會用於作業目的。 如有需要，可存取完整的有效負載，以進行進階使用個案或未來擴充。