IBM Cloud Docs
拉取请求管道

拉取请求管道

拉取请求管道对指定应用程序存储库的拉取请求运行一组合规性状态检查。

由于合规性状态检查失败，可能会阻止将拉取请求合并到主分支中的尝试。 针对主分支打开或更新拉取请求会触发拉取请求管道运行。 您可以在 定制脚本 中针对管道和测试运行自己的设置。

阶段和任务

下表列出了在 PR 管道中运行的任务。 此外，该表还提供了以下每个阶段的概述:

  • 任务或阶段: 这是指在 .pipeline-config.yaml 配置文件中定义的阶段的名称。

  • 简短描述: 提供阶段执行期间执行的操作的简明说明。

  • 允许定制: 这指示用户是否具有通过在 .pipeline-config.yaml 文件中插入定制脚本来修改或替换阶段的缺省行为的灵活性。

  • 默认参考实现：这表示DevSecOps管道是否为该阶段提供了预定义或默认实现。 值得注意的是，对于 unit-tests 或 setup 等特定阶段，DevSecOps 管道不提供任何开箱即用的实施。 而是需要用户提供定制脚本或根据其应用程序需求定制的代码。

  • 证据收集: 指示阶段是否执行标准证据收集。 当 DevSecOps Pipeline 为某一阶段提供参考实现时，证据收集将开箱即用。 但是，如果 用户 选择修改或替换这些预定义阶段，那么他们必须确保其定制实现包含相应的证据收集。 在DevSecOps管道没有提供开箱即用实施的阶段，用户也要承担同样的责任，因为他们必须执行证据收集。 该列指示负责执行证据收集的实体 (用户/管道)。

  • 允许跳过 (适用于版本> = 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 文件来定制阶段的更多信息，请参阅 定制脚本 和 管道参数。

检测私钥扫描

IBM 检测私钥 工具可识别私钥在应用程序代码中可见的位置。 此处 提供了有关为扫描设置存储库的更多信息。

扫描并检查一致性检查

扫描或检查 描述
Code Risk Analyzer 漏洞扫描 查找所有应用程序包依赖关系，容器基本映像和操作系统包的漏洞。 使用 Code Risk Analyzer 工具。
Code Risk Analyzer CIS 检查 在 Kubernetes 部署清单上运行 配置检查。 使用 Code Risk Analyzer 工具。
Code Risk Analyzer 材料清单 (BOM) 检查 用于捕获所有依赖关系的 pedigree 的指定存储库的 BOM。 将以不同的粒度收集此 BOM。 例如，BOM 捕获构建中使用的基本映像的列表，基本映像中的软件包的列表以及安装在基本映像上的应用程序软件包的列表。 BOM 充当分析结果的参考标准，并可能用于实施策略检测点。 使用 Code Risk Analyzer 工具。

| 检查分支保护设置是否正确。|

这些脚本在管道感知的所有应用程序存储库上运行。 要向这些扫描添加存储库，请使用安装阶段中提供的 pipelinectl 界面。

有关用户脚本阶段的预期输出的更多信息，请参阅 定制脚本。

任务作业

合规性扫描和检查
任务作业 描述
code-pr-start 克隆应用程序和 DevSecOps repos，并为 Git Repos and Issue Tracking repos 的状态检查设置初始挂起状态。
code-setup 用户定义的设置定制脚本的占位符，用户可以在该脚本中完成其管道设置。
code-detect-secrets 运行检测私钥扫描以识别私钥在应用程序代码中的可见位置。
code-unit-tests 用户定义的测试定制脚本的占位符，用户可以在该脚本中运行自己的测试。
code-pr-finish 运行所有必需的合规性检查，将结果注释到拉取请求，并在 Git Repos and Issue Tracking 存储库上设置结果。

将 PR/MR 更改用于管道配置 repo

如果 PR 项目应考虑来自 PR/MR 的配置文件/脚本的更改，则配置版本库和分支应为空，设置如下：

  • 环境变量 one-pipeline-repo、one-pipeline-config-repo 和 pipeline-config-repo 为空或未在环境变量中指定
  • 环境变量 one-pipeline-config-branch 和 pipeline-config-branch 为空或未在环境变量中指定。

将拉取请求与问题合并

您可以使用管理员权限将状态检查失败的拉取请求合并到存储库。 但是，这些拉取请求会注册 failure，从而生成失败任务的证据。 此结果包含在证据摘要和变更请求描述中，并影响 Security and Compliance Center上的最终合规性分数。

确保在公关管道中收集证据

公关管道支持证据收集和问题管理。 默认情况下，公关管道不会收集证据或打开任何问题，但用户可以选择使用该功能。 为了启用证据收集和问题管理，请将环境变量 collect-evidence-in-pr 设置为以下枚举之一：

  • none：（默认）将 collect-evidence-in-pr 设置为 none，以防止在 PR 管道中收集证据。
  • all: 将 collect-evidence-in-pr 设为 all 以收集所有证据，无论 PR 管道的状态如何。 问题将根据 collect-evidence 脚本打开、更新或关闭。
  • success: 将 collect-evidence-in-pr 设为 success 仅在整个 PR 管道成功运行时收集证据。 如果公关管道失败，证据将无法收集或发布到证据锁，问题管理也将无法进行。

注意：由于 PR 管道的运行频率通常很高，因此选择正确的 collect-evidence-in-pr 模式可以避免不必要的证据收集。 建议在开发阶段或预计会发生故障的情况下选择 success 模式，以防止在管道发生故障时收集证据。

如果 PR 管道触发了同步管道，则不支持 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 管道中启用/禁用该功能。 默认情况下已启用。

设置 PR 管道以处理 Github 合并队列 PR

合并队列是 Github 的一项功能，它能自动将拉取请求合并到繁忙的分支中，确保分支不会被不兼容的更改破坏，从而帮助提高速度。 有关设置和使用 Github 合并队列的更多信息，请点击此处。

创建新的 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）

保存触发器。

测试合并队列触发器

  • 针对应用程序源代码库的主分支创建一个新的拉取请求。
  • 观察：“标准”DevSecOps PR 管道已触发
  • 仍然在 PR 页面，点击 Merge when ready，然后点击 Attempt merge when ready- 一旦“标准”PR 完成，这将 enqueue PR 到合并队列。
  • 等待“标准”DevSecOps PR 成功完成
  • 观察：PR 管道完成后，PR 将添加到合并队列，并触发合并队列 PR：
    • 等待合并队列 PR 完成
    • 如果成功，PR 将与注释合并，如 Merged via the queue into main with commit abcdefg
    • 如果不成功（例如：合规性检查失败），PR 将不会自动合并，并从合并队列中删除。

PR 有效载荷概述

有效内容

有效载荷是一个通用术语，用于描述作为事件或请求的一部分传输的结构化数据块，通常采用 JSON 格式。 有效载荷通常用于网络钩子、应用程序接口和自动化系统，以机器可读的形式传递相关信息。

根据上下文，有效载荷可以代表多种内容--例如，构建元数据、用户活动、问题更新，或者本例中的拉取请求详细信息。

PR 有效载荷

cd-devsecops-pr-payload

PR 有效载荷是有效载荷的一个特定实例，它封装了有关拉取请求 (PR) 的元数据和上下文信息。 它在拉取请求事件发生时生成，并提供与该 PR 相关的关键属性的结构化访问。

该有效载荷包括各种数据，如

  • 公关标题和描述
  • 作者和审稿人
  • 源分支（头分支）和目标分支（基分支
  • 提交历史和 SHA 参考资料
  • 存储库详细信息
  • 时间戳、标签、状态等

虽然整个有效载荷包含大量信息，但目前只提取了特定字段的子集，并将其作为环境变量公开，供管道、脚本和配置文件使用。

从 PR 有效载荷中提取的环境属性

下列环境变量目前来自 PR 有效载荷，并被积极使用：

变量名称 描述
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 有效载荷还包括许多其他字段。 不过，目前只有提取的子集用于业务目的。 如有需要，还可接入完整的有效载荷，用于高级用例或未来扩展。