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 呼叫以及日誌中顯示的回應,以判斷失敗的確切原因。