DevOps Insights CLI

IBM Cloud® DevOps Insights CLI 提供了一组命令,可用于将构建与 DevOps Insights 集成。 使用两种不同类型的命令:CLI 使用命令和与 DevOps Insights 集成的 CLI 命令。

DevOps Insights 该服务已停止提供,不再可用。 了解更多

准备工作

  • 安装 IBM Cloud CLI。 有关说明,请参阅 下载 IBM Cloud CLI。

  • 添加 IBM Cloud CLI 插件。 运行以下命令:

ibmcloud plugin install doi
  • 确保可以使用为工具链配置的 DevOps Insights 工具访问工具链。 有关工具链的更多信息,请参阅通过应用程序创建工具链。

  • 使用以下方法之一指定工具链 ID:

    • 将工具链 ID 指定为命令的 CLI 参数。
    • 设置 TOOLCHAIN_ID 环境变量。
    • IBM Cloud® Continuous Delivery 管道可能会自动设置 PIPELINE_TOOLCHAIN_ID 环境变量。

    CLI 需要工具链 ID 的值。 CLI 参数中指定的工具链 ID 值会覆盖环境变量的值。

    工具链标识可在浏览器中显示的工具链 URL 中找到。 如果使用 IBM® Continuous Delivery Pipeline for IBM Cloud®,可以设置工具链 ID,将构建数据发送到不同的工具链。 有关更多信息,请参阅将来自多个源的数据聚集到一个工具链中。

登录

使用此命令可登录到 IBM Cloud。 API_KEY 必须有权访问工具链。

ibmcloud login --apikey API_KEY

使用专用端点登录 CLI

使用 CLI 时,为了加强对数据的控制和安全性,您可以选择使用专用路由到 IBM Cloud 端点。 您必须先在您的账户中启用虚拟路由和转发功能,然后才能启用 IBM Cloud 私有服务端点。 有关配置账户以支持私有连接选项的更多信息,请参阅《 启用 VRF 和服务端点 》。

使用以下命令通过 CLI 登录专用端点。 API_KEY 必须有权访问工具链。

ibmcloud login -a private.cloud.ibm.com --apikey API_KEY

CLI 用法命令

DevOps Insights帮助信息

以下命令会显示 DevOps Insights 命令的列表:

 ibmcloud doi --help

DevOps Insights 命令帮助信息

以下命令会显示某条命令所需的参数详情:

 ibmcloud doi <command> --help

您可以向任何命令传递 --region 参数。 通过将该参数的值设置为工具链的 ibmcloud 区域,CLI 就无需确定工具链处于哪个区域,从而提高了效率和可靠性。 该参数为可选参数,以便与早期版本兼容。

用于集成 DevOps Insights 的命令

将 CLI 用于构建时,必须发布构建记录。

传给 CLI 的 logicalappname 和 buildnumber 参数值必须在所有命令调用中保持一致。

发布构建记录

以下命令会将构建记录发布到 DevOps Insights:

 ibmcloud doi buildrecord-publish --branch BRANCH --repositoryurl REPOSITORYURL --commitid COMMITID --status STATUS --logicalappname LOGICALAPPNAME --buildnumber BUILDNUMBER --toolchainid TOOLCHAINID [--joburl JOBURL] [--region REGION]

下面是用于发布构建记录的命令选项。

发布构建记录的命令选项
命令选项 必需或可选 描述
-B, --branch 必需 要执行构建的存储库分支。
-R, --repositoryurl 必需 Git 存储库的 URL。
-C, --commitid 必需 Git 提交标识。
-S, --status 必需 构建状态。 可接受的值为:pass 和 fail。
-L, --logicalappname 必需 应用程序的名称。
-N, --buildnumber 必需 用于标识构建的任何字符串。
-I, --toolchainid 必需 如果设置了 TOOLCHAIN_ID 环境变量,则此标记为可选标记。 如果同时提供环境变量和标志,则标志的值优先于环境变量的值。
-J, --joburl 可选 CLI 在 IBM® Continuous Delivery Pipeline for IBM Cloud® 中自动设置的作业构建日志 URL。
--region 必需 工具链的 ibmcloud 区域。 使用专用端点时需要使用此值。 这是一个可选项,但在使用公共端点时很有必要。

示例

ibmcloud doi buildrecord-publish  -B master -R "https://github.com/oic/dlms.git" -C dff7884b9168168d91cb9e5aec78e93db0fa80d9 -S pass -L testapp -N master:199 -I b531487c-9c22-4f3b-9d20-5be408d57891 --region eu-gb
or
ibmcloud doi buildrecord-publish  --branch master --repositoryurl "https://github.com/oic/dlms.git" --commitid dff7884b9168168d91cb9e5aec78e93db0fa80d9 --status pass --logicalappname testapp --buildnumber master:199 --toolchainid b531487c-9c22-4f3b-9d20-5be408d57891

发布测试记录

以下命令用于将测试记录发布到 DevOps Insights:

 ibmcloud doi testrecord-publish --filelocation FILELOCATION --type TYPE --logicalappname LOGICALAPPNAME --buildnumber BUILDNUMBER --toolchainid TOOLCHAINID [--drilldownurl DRILLDOWNURL] [--env ENV] [--sqtoken SONARQUBE_TOKEN] [--tags TAGS] [--region REGION]

下面是用于发布测试记录的命令选项。

发布构建记录的命令选项
命令选项 必需或可选 描述
-F, --filelocation 必需 要上传的结果的位置。 这可以是单个文件、整个目录或与通配符表达式匹配的几个文件。
-T, --type 必需 要上传的测试结果的类型。
-L, --logicalappname 必需 应用程序的名称。
-N, --buildnumber 必需 用于标识构建的任何字符串。
-I, --toolchainid 必需 如果设置了 TOOLCHAIN_ID 环境变量,则此标记为可选标记。 如果同时提供环境变量和标志,则标志的值优先于环境变量的值。
-U, --drilldownurl 可选 可以在其中找到有关测试结果的更多信息的 URL。 如果此 URL 无效,那么会忽略此选项。
-E, --env 可选 要与测试结果关联的环境名称。 对于单元测试、代码覆盖范围测试和静态安全扫描,将忽略此选项。
-K, --sqtoken 可选 此命令是 SonarQube 令牌。 仅当指定的类型为 SonarQube 时才有效。 用于从 SonarQube 服务器拉取更多信息。
--tags 可选 指定以逗号分隔的标记列表,以便与此测试结果关联。
--region 必需 工具链的 ibmcloud 区域。 使用专用端点时需要使用此值。 这是一个可选项,但在使用公共端点时很有必要。

示例

ibmcloud doi testrecord-publish -F "tests/fvt/*.json" -T fvt -L testapp -N master:199 -I b531487c-9c22-4f3b-9d20-5be408d57891 --tags "CC,app1"
or
ibmcloud doi testrecord-publish --filelocation "tests/fvt/*.json" --type fvt --logicalappname testapp --buildnumber master:199 --toolchainid b531487c-9c22-4f3b-9d20-5be408d57891 --region ca-tor

支持下列测试类型:

测试记录类型
类型 描述
unittest 单元测试结果
fvt 功能验证测试 (FVT) 结果
code 代码覆盖结果
sonarqube SonarQube 扫描结果
vulnerabilityadvisor 来自 IBM Vulnerability Advisor on Cloud 的 Vulnerability Advisor 结果
cratf 代码风险分析器生成的 Terraform 报告
crabom 代码风险分析器生成的材料清单 (BOM) 报告
cradeploy 代码风险分析器生成的部署报告
cracve 代码风险分析器生成的漏洞报告
zapscan OWASP Zed 攻击代理 (ZAP) 扫描报告

IBM Application Security on Cloud 1.0.0 staticsecurityscan 和 dynamicsecurityscan 测试类型)。 所有 IBM Application Security on Cloud 1.0.0 支持均由 HCL 提供。 更多信息,请参阅 HCL AppScan 文档。

发布部署记录

以下命令用于将部署记录发布到 DevOps Insights:

 ibmcloud doi deployrecord-publish --env ENV --status STATUS --logicalappname LOGICALAPPNAME --buildnumber BUILDNUMBER --toolchainid TOOLCHAINID [--joburl JOBURL] [--appurl APPURL] [--region REGION]
发布部署记录的命令选项
命令选项 必需或可选 描述
-E, --env 必需 管道作业在其中部署应用程序的环境。
-S, --status 必需 部署状态。 此值必须为 pass 或 fail。
-L, --logicalappname 必需 应用程序的名称。
-N, --buildnumber 必需 用于标识构建的任何字符串。
-I, --toolchainid 必需 如果设置了 TOOLCHAIN_ID 环境变量,则此标记为可选标记。 如果同时提供环境变量和标志,则标志的值优先于环境变量的值。
-A, --appurl 可选 在其中运行已部署应用程序的 URL。
-J, --joburl 可选 CLI 在 IBM® Continuous Delivery Pipeline for IBM Cloud® 中自动设置的作业构建日志 URL。
--region 必需 工具链的 ibmcloud 区域。 使用专用端点时需要使用此值。 这是一个可选项,但在使用公共端点时很有必要。

示例

ibmcloud doi deployrecord-publish -E "staging" -S pass -L testapp -N master:199 -I b531487c-9c22-4f3b-9d20-5be408d57891 --region au-syd
or
ibmcloud doi deployrecord-publish --env "staging" --status pass --logicalappname testapp --buildnumber master:199 --toolchainid b531487c-9c22-4f3b-9d20-5be408d57891

评估检测点

以下命令用于评估 DevOps Insights 检测点:

 ibmcloud doi gate-evaluate --policy POLICY --logicalappname LOGICALAPPNAME --buildnumber BUILDNUMBER --toolchainid TOOLCHAINID [--forcedecision] [--ruletype RULETYPE] [--region REGION]

下面是用于评估检测点的命令选项:

评估闸门的指挥选项
命令选项 必需或可选 描述
-P, --policy 必需 检测点用于制定决策的策略的名称。
-L, --logicalappname 必需 应用程序的名称。
-N, --buildnumber 必需 用于标识构建的任何字符串。
-I, --toolchainid 必需 如果设置了 TOOLCHAIN_ID 环境变量,则此标记为可选标记。 如果同时提供环境变量和标志,则标志的值优先于环境变量的值。
-D, --forcedecision 可选 将值设置为 true 可在策略评估失败时退出并显示错误代码。 如果未指定此选项,那么值缺省为 false。
-E, --ruletype 可选 要考虑的规则类型。 如果包含此选项,那么在决策制定过程中仅考虑此类型的规则。
--region 必需 工具链的 ibmcloud 区域。 使用专用端点时需要使用此值。 这是一个可选项,但在使用公共端点时很有必要。

示例

ibmcloud doi gate-evaluate -P "policyname" -D true -L testapp -N master:199 -I b531487c-9c22-4f3b-9d20-5be408d57891 --region br-sao
or
ibmcloud doi gate-evaluate --policy "policyname" --forcedecision true --logicalappname testapp --buildnumber master:199 --toolchainid b531487c-9c22-4f3b-9d20-5be408d57891

更新自定义数据集和政策

以下命令可创建和更新工具链的自定义数据集和策略:

 ibmcloud doi policies-update --file FILELOCATION --toolchainid TOOLCHAINID [--dryrun] [--region REGION]

以下是更新自定义数据集和策略的命令选项:

更新自定义数据集和策略的命令选项
命令选项 必需或可选 描述
-F, --file 必需 JSON 文件的位置,该文件包含要添加或更新的自定义数据集和策略列表。 绝对路径和相对路径均可接受。
-I, --toolchainid 必需 如果设置了 TOOLCHAIN_ID 环境变量,则此标记为可选标记。 如果同时提供环境变量和标志,则标志的值优先于环境变量的值。
-D, --dryrun 可选 只模拟变化,不进行更新的选项。
--region 必需 工具链的 ibmcloud 区域。 使用专用端点时需要使用此值。 这是一个可选项,但在使用公共端点时很有必要。

示例

ibmcloud doi policies-update -F "policies/policy.json" -I b531487c-9c22-4f3b-9d20-5be408d57891 --region jp-tok
or
ibmcloud doi policies-update --file "policies/policy.json" --toolchainid b531487c-9c22-4f3b-9d20-5be408d57891

updatepolicies 命令的 JSON 文件结构

有效的 JSON 文件结构包含两个字段:

{
      "custom_datasets": [],
      "policies": []
}
  • 您可以为阵列指定任意数量的策略(和自定义数据集)。
  • 如果工具链存在指定的策略(和自定义数据集),则会更新或创建该策略。
  • custom_datasets 或 policies 数组可以为空,也可以都为空。
  • type_of_test 自定义数据集的唯一有效值是 test 和 code。
  • 如果工具链存在自定义数据集,则可在 JSON 文件中定义的策略规则中使用。 您并不总是需要在 JSON 文件中定义自定义数据集。
  • policies-update 命令提供的 JSON 示例文件列出了可在策略中指定的所有规则类型。 这些规则中的所有字段都是必填字段。
  • 每个数据集只使用一条规则。
  • 规则中的名称字段是可选的。

policies-update 命令的 JSON 文件示例

此 JSON 示例文件包含两个自定义数据集和两个策略。 第一个策略 name: "Orders" 包含可在策略中使用的所有规则类型。

{
  "custom_datasets": [
 .  {
      "lifecycle_stage": "integrationtest",
      "type_of_test": "test",
      "label": "Integration Test"
    },
    {
      "lifecycle_stage": "covtest",
      "type_of_test": "code",
      "label": "Coverage Test"
    }
  ],
  "policies": [
    {
      "name": "Orders",
      "description": "Composite Policy.",
      "rules": [
        {
          "name": "rule1",
 .        "description": "Unit Test Rule with regression",
          "stage": "unittest",
          "percentPass": 100,
          "criticalTests": [
            "Get Weather with incomplete zip code"
          ],
          "regressionCheck": true
        },
        {
          "name": "rule2",
          "description": "Unit Test Rule without regression",
          "stage": "integrationtest",
          "percentPass": 98,
          "criticalTests": [
            "'Get Weather with incomplete zip code'"
          ],
        },
        {
          "name": "rule3",
          "description": "Functional test Rule",
          "stage": "fvt",
          "percentPass": 98,
          "criticalTests": [
            "'Get Weather with incomplete zip code'"
          ],
        },
        {
          "name": "rule4",
          "description": "Code Coverage rule",
          "stage": "code",
          "codeCoverage": 98,
        },
        {
          "name": "rule5",
          "description": "Custom dataset rule",
          "stage": "covtest",
          "codeCoverage": 60,
        },
        {
          "name": "rule6",
          "description": "Static Security Scan rule",
          "stage": "staticsecurityscan",
          "highSeverity": 40,
          "mediumSeverity": 5,
          "lowSeverity": 9
        },
        {
          "name": "rule7",
         "description": "Dynamic Security Scan rule",
          "stage": "dynamicsecurityscan",
          "highSeverity": 40,
          "mediumSeverity": 5,
          "lowSeverity": 9
        },
        {
          "name": "rule8",
          "description": "Sonarqube rule",
          "stage": "sonarqube"
        },
        {
          "name": "rule9",
          "description": "Vulnerability rule",
          "stage": "vulnerabilityadvisor"
        }
      ]
    },
    {
      "name": "UI",
      "description": "Policy to check Unit Test.",
      "rules": [
        {
          "name": "Unit Test Rule",
          "description": "Unit Test Rule",
          "stage": "integrationtest",
          "percentPass": 100,
          "criticalTests": []
        }
      ]
    }
  ]
}

常见问题

获取有关使用 DevOps Insights CLI 的常见问题答案。

为什么 CLI 失败时会出现“您没有访问工具链的权限”信息?

用于登录 IBM Cloud 的 API_KEY 环境变量必须能够访问工具链。 此外,请确认已将 DevOps Insights 工具集成添加到工具链中。

CLI 运行成功,为什么仪表板上没有显示数据?

确保传给 CLI 的 logicalappname 和 buildnumber 参数值在构建的所有阶段都相同。 此外,还要验证是否上传了构建记录。 如果没有构建记录,为特定构建上传的测试记录数据不会显示在仪表板上。

CLI 与 Sonarqube 服务器通信超时,有办法延长超时时间吗?

默认超时时间为 60 秒。 在调用 DevOps Insights CLI 之前,请设置 IBMCLOUD_HTTP_TIMEOUT 环境变量。 其值为秒数。

    export IBMCLOUD_HTTP_TIMEOUT=120

如何确定 CLI 失败的原因?

在调用 DevOps Insights CLI 之前,请将 IBMCLOUD_TRACE 环境变量设置为 true,以打开调试日志。

    export IBMCLOUD_TRACE=true

观察 API 调用和日志中显示的响应,以确定失败的确切原因。