DevOps Insights CLI

IBM Cloud® DevOps Insights CLI は、ビルドを DevOps Insights と統合するために使用できる一連のコマンドを提供します。 2つの異なるタイプのコマンドを使用する:CLI使用コマンドと、 DevOps Insights と統合するためのCLIコマンドです。

DevOps Insights 提供期間が終了したため、ご利用いただけなくなりました。 詳しくは、こちらを参照してください。

開始前に

  • IBM Cloud CLI をインストールします。 手順については、IBM Cloud CLI のダウンロードを参照してください。

  • IBM Cloud CLIプラグインを追加します。 以下のコマンドを実行します。

ibmcloud plugin install doi
  • ツールチェーンに設定されている DevOps Insights ツールを使ってツールチェーンにアクセスできることを確認してください。 ツールチェーンについて詳しくは、アプリからのツールチェーンの作成を参照してください。

  • 以下のいずれかの方法でツールチェーンIDを指定する:

    • コマンドのCLIパラメータとしてツールチェーンIDを指定する。
    • TOOLCHAIN_ID という環境変数を設定してください。
    • IBM Cloud® Continuous Delivery パイプラインが自動的に PIPELINE_TOOLCHAIN_ID 環境変数を設定するかもしれない。

    CLIはツールチェーンIDの値を必要とする。 CLIパラメータで指定されたツールチェーンIDの値は、環境変数の値よりも優先される。

    ツールチェーン ID はブラウザーに表示されるツールチェーンの URL で確認できます。 IBM® Continuous Delivery Pipeline for IBM Cloud® を使用している場合は、ツールチェーンIDを設定して、ビルドデータを別のツールチェーンに送ることができる。 詳細については、複数のソースのデータを 1 つのツールチェーンに集約する方法を参照してください。

ログイン

このコマンドは、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 オプション IBM® Continuous Delivery Pipeline for IBM Cloud® で CLI によって自動的に設定される、ジョブのビルド・ログの 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 必須 アップロードする結果の場所。 1 つのファイル、ディレクトリー全体、または、ワイルドカード式と一致するファイルにすることができます。
-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 の脆弱性アドバイザー結果
cratf Code Risk Analyzerによって生成されたTerraformレポート
crabom コード・リスク・アナライザーが作成した部品表(BOM)レポート
cradeploy コード・リスク・アナライザーによって生成されたデプロイメント・レポート
cracve Code Risk Analyzerによって生成された脆弱性レポート
zapscan OWASP Zed Attack Proxy (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 オプション IBM® Continuous Delivery Pipeline for IBM Cloud® で CLI によって自動的に設定される、ジョブのビルド・ログの 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ファイル構造は、2つのフィールドを含む:

{
      "custom_datasets": [],
      "policies": []
}
  • アレイにはいくつでもポリシー(およびカスタムデータセット)を指定できる。
  • 指定されたポリシー(およびカスタムデータセット)がツールチェーンに存在する場合、ポリシーが更新または作成されます。
  • custom_datasets 、 policies 配列のどちらかが空でも、両方が空でも構わない。
  • type_of_test カスタムデータセットに有効な値は、 test と code のみです。
  • ツールチェーンのカスタム・データセットが存在する場合、JSONファイル内で定義されるポリシー・ルールで使用することができる。 JSONファイル内でカスタム・データ・セットを定義する必要は必ずしもありません。
  • policies-update コマンドで提供されるサンプル JSON ファイルには、ポリシーで指定できるすべてのルール タイプがリストされています。 これらのルールのフィールドはすべて必須である。
  • 1つのデータセットにつき1つのルールだけを使用する。
  • ルール内の名前フィールドは任意である。

policies-update コマンドのサンプルJSONファイル

このサンプルJSONファイルには、2つのカスタムデータセットと2つのポリシーが含まれています。 最初のポリシー 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": []
        }
      ]
    }
  ]
}

FAQ

DevOps Insights CLI の使用に関するよくある質問への回答をご覧ください。

なぜCLIは "You do not have access to toolchain "というメッセージで失敗するのですか?

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 呼び出しと応答を監視して、失敗の正確な理由を判別してください。