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