DevOps Insights CLI
IBM Cloud® DevOps Insights CLI 提供了一組指令,您可以使用這些指令將您的建置與 DevOps Insights 整合。 使用兩種不同類型的指令:CLI 使用指令和 CLI 指令與 DevOps Insights 整合。
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 值會取代環境變數的值。
工具鏈 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 確定 ID。 |
-S, --status |
必要 | 建置狀態。 可接受的值:pass 及 fail。 |
-L, --logicalappname |
必要 | 應用程式的名稱。 |
-N, --buildnumber |
必要 | 識別建置的任何字串。 |
-I, --toolchainid |
必要 | 如果已設定 TOOLCHAIN_ID 環境變數,則此標記是可選的。 如果同時提供環境變數和旗標,旗標的值會取代環境變數的值。 |
-J, --joburl |
選用 | 工作建置日誌的 URL,由 CLI 自動在 IBM® Continuous Delivery Pipeline for IBM Cloud® 設定。 |
--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 |
由 Code Risk Analyzer 產生的物料清單 (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 |
選用 | 工作建置日誌的 URL,由 CLI 自動在 IBM® Continuous Delivery Pipeline for IBM Cloud® 設定。 |
--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 呼叫以及日誌中顯示的回應,以判斷失敗的確切原因。