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的 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
支持下列测试类型:
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 已不再发布(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 调用和日志中显示的响应,以确定失败的确切原因。