IBM Cloud Docs
DevOps Insights CLI

DevOps Insights CLI

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

准备工作

  • 安装 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 的 logicalappnamebuildnumber 参数值必须在所有命令调用中保持一致。

发布构建记录

以下命令会将构建记录发布到 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 必需 构建状态。 可接受的值为:passfail
-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 staticsecurityscandynamicsecurityscan 测试类型)。 所有 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_datasetspolicies 数组可以为空,也可以都为空。
  • type_of_test 自定义数据集的唯一有效值是 testcode
  • 如果工具链存在自定义数据集,则可在 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 的 logicalappnamebuildnumber 参数值在构建的所有阶段都相同。 此外,还要验证是否上传了构建记录。 如果没有构建记录,为特定构建上传的测试记录数据不会显示在仪表板上。

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 调用和日志中显示的响应,以确定失败的确切原因。