IBM Cloud Docs
DevOps Insights CLI

DevOps Insights CLI

IBM Cloud® DevOps Insights CLI 提供了一组命令,您可以使用它们将构建与 DevOps Insights 集成。 使用两种不同的命令:CLI使用命令和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的 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

支持下列测试类型:

测试记录类型
Type 描述
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 调用和日志中显示的响应,以确定失败的确切原因。