DevOps Insights-CLI
Die IBM Cloud® DevOps Insights CLI bietet eine Reihe von Befehlen, die Sie verwenden können, um Ihren Build in DevOps Insights zu integrieren. Verwenden Sie zwei verschiedene Arten von Befehlen: CLI-Nutzungsbefehle und CLI-Befehle zur Integration mit DevOps Insights.
DevOps Insights Das Produkt wurde eingestellt und ist nicht mehr verfügbar. Weitere Informationen
Vorbereitende Schritte
-
Installieren Sie die IBM Cloud-Befehlszeilenschnittstelle. Anweisungen finden Sie in IBM Cloud -CLI herunterladen.
-
Fügen Sie das CLI-Plug-in für IBM Cloud hinzu. Führen Sie den folgenden Befehl aus:
ibmcloud plugin install doi
-
Vergewissern Sie sich, dass Sie mit dem Werkzeug DevOps Insights, das für diese Werkzeugkette konfiguriert ist, auf eine Werkzeugkette zugreifen können. Weitere Informationen zu Toolchains finden Sie unter Toolchain über eine App erstellen.
-
Geben Sie die Toolchain-ID mit einer der folgenden Methoden an:
- Geben Sie die Toolchain-ID als CLI-Parameter für den Befehl an.
- Setzen Sie die
TOOLCHAIN_IDUmgebungsvariable. - Ihre IBM Cloud® Continuous Delivery Pipeline setzt möglicherweise automatisch die Umgebungsvariable
PIPELINE_TOOLCHAIN_ID.
Die CLI benötigt den Wert der Toolchain-ID. Der Wert der Toolchain-ID, der im CLI-Parameter angegeben ist, hat Vorrang vor dem Wert der Umgebungsvariablen.
Die Toolchain-ID ist in der Toolchain-URL enthalten, die im Browser angezeigt wird. Wenn Sie IBM® Continuous Delivery Pipeline for IBM Cloud® verwenden, können Sie die Toolchain-ID festlegen, um Ihre Build-Daten an eine andere Toolchain zu senden. Weitere Informationen hierzu finden Sie im Abschnitt zum Zusammenfassen von Daten aus mehreren Quellen in einer Toolchain.
Anmeldung
Verwenden Sie den folgenden Befehl für die Anmeldung bei IBM Cloud. Der API-Schlüssel (API_KEY) muss Zugriff auf die Toolchain haben.
ibmcloud login --apikey API_KEY
Melden Sie sich über einen privaten Endpunkt bei der CLI an
Um die Kontrolle und Sicherheit Ihrer Daten bei der Verwendung von CLI zu verbessern, haben Sie die Möglichkeit, private Routen zu IBM Cloud Endpunkten zu verwenden. Zuerst müssen Sie Virtual Routing and Forwarding (VRF) in Ihrem Konto aktivieren. Anschließend können Sie die Verwendung von privaten IBM Cloud-Serviceendpunkten aktivieren. Weitere Informationen zum Einrichten Ihres Kontos zwecks Unterstützung der Option der privaten Konnektivität enthält der Abschnitt VRF und Serviceendpunkte aktivieren.
Verwenden Sie den folgenden Befehl, um sich über die CLI bei einem privaten Endpunkt anzumelden. Der API-Schlüssel (API_KEY) muss Zugriff auf die Toolchain haben.
ibmcloud login -a private.cloud.ibm.com --apikey API_KEY
Befehle zur Verwendung der CLI
DevOps Insights-Hilfe
Mit dem folgenden Befehl wird die Liste der DevOps Insights-Befehle angezeigt:
ibmcloud doi --help
Hilfe für DevOps Insights-Befehle
Der folgende Befehl zeigt die Details der für einen Befehl erforderlichen Flags an:
ibmcloud doi <command> --help
Sie können jedem der Befehle einen Parameter --region übergeben. Wenn der Wert dieses Parameters auf die Region ibmcloud der Werkzeugkette gesetzt wird, muss die Befehlszeilenschnittstelle nicht feststellen, in welcher
Region sich die Werkzeugkette befindet, was die Effizienz und Zuverlässigkeit erhöht. Dieser Parameter ist aus Gründen der Kompatibilität mit früheren Versionen optional.
Befehle für die Integration mit DevOps Insights
Wenn Sie die Befehlszeilenschnittstelle für einen Build verwenden, müssen Sie einen Builddatensatz veröffentlichen.
Der Wert der Parameter logicalappname und buildnumber, die an die CLI übergeben werden, muss bei allen Befehlsaufrufen gleich bleiben.
Erstellen eines Builddatensatzes
Mit dem folgenden Befehl wird ein Builddatensatz in DevOps Insights veröffentlicht:
ibmcloud doi buildrecord-publish --branch BRANCH --repositoryurl REPOSITORYURL --commitid COMMITID --status STATUS --logicalappname LOGICALAPPNAME --buildnumber BUILDNUMBER --toolchainid TOOLCHAINID [--joburl JOBURL] [--region REGION]
Die folgenden Befehlsoptionen sind für das Veröffentlichen von Builddatensätzen verfügbar.
| Befehlsoptionen | Erforderlich oder optional | Beschreibung |
|---|---|---|
-B, --branch |
Erforderlich | Die Repositoryverzweigung, in der der Build ausgeführt wird. |
-R, --repositoryurl |
Erforderlich | Die URL des Git-Repositorys. |
-C, --commitid |
Erforderlich | Die Git-Commit-ID. |
-S, --status |
Erforderlich | Der Buildstatus. Zulässige Werte sind pass und fail. |
-L, --logicalappname |
Erforderlich | Der Name der Anwendung. |
-N, --buildnumber |
Erforderlich | Eine beliebige Zeichenfolge zur Kennzeichnung des Builds. |
-I, --toolchainid |
Erforderlich | Wenn die Umgebungsvariable TOOLCHAIN_ID gesetzt ist, ist dieses Flag optional. Wenn sowohl die Umgebungsvariable als auch das Flag angegeben werden, hat der Wert des Flags Vorrang vor dem Wert der Umgebungsvariablen. |
-J, --joburl |
Optionale | Die URL für die Buildprotokolle des Jobs, die automatisch von der CLI in IBM® Continuous Delivery Pipeline for IBM Cloud® festgelegt wird. |
--region |
Erforderlich | Die Region ibmcloud der Toolchain. Dieser Wert ist erforderlich, wenn private Endpunkte verwendet werden. Sie ist optional, aber im Falle von öffentlichen Endpunkten gut zu gebrauchen. |
Beispiel
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
Veröffentlichung eines Testdatensatzes
Mit dem folgenden Befehl wird ein Testdatensatz in DevOps Insights veröffentlicht:
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]
Die folgenden Befehlsoptionen sind für das Veröffentlichen von Testdatensätzen verfügbar.
| Befehlsoptionen | Erforderlich oder optional | Beschreibung |
|---|---|---|
-F, --filelocation |
Erforderlich | Die Position der Ergebnisse, die hochgeladen werden sollen. Dabei kann es sich um eine einzelne Datei, ein vollständiges Verzeichnis oder mehrere Dateien handeln, die einem Ausdruck mit Platzhalterzeichen entsprechen. |
-T, --type |
Erforderlich | Der Typ der Testergebnisse, die hochgeladen werden sollen. |
-L, --logicalappname |
Erforderlich | Der Name der Anwendung. |
-N, --buildnumber |
Erforderlich | Eine beliebige Zeichenfolge zur Kennzeichnung des Builds. |
-I, --toolchainid |
Erforderlich | Wenn die Umgebungsvariable TOOLCHAIN_ID gesetzt ist, ist dieses Flag optional. Wenn sowohl die Umgebungsvariable als auch das Flag angegeben werden, hat der Wert des Flags Vorrang vor dem Wert der Umgebungsvariablen. |
-U, --drilldownurl |
Optionale | Eine URL für weitere Informationen zu den Testergebnissen. Wenn diese URL ungültig ist, wird die Option ignoriert. |
-E, --env |
Optionale | Der Umgebungsname, der den Testergebnissen zugeordnet werden soll. Diese Option wird bei Komponententests, Codeabdeckungstests und Scans zur statischen Sicherheit ignoriert. |
-K, --sqtoken |
Optionale | Dieser Befehl ist ein SonarQube-Token. Nur gültig, wenn es sich bei dem angegebenen Typ um SonarQube handelt. Wird zum Extrahieren von weiteren Informationen aus dem SonarQube-Server verwendet. |
--tags |
Optionale | Geben Sie eine durch Komma getrennte Liste von Tags an, die mit diesem Testergebnis verknüpft werden sollen. |
--region |
Erforderlich | Die Region ibmcloud der Toolchain. Dieser Wert ist erforderlich, wenn private Endpunkte verwendet werden. Sie ist optional, aber im Falle von öffentlichen Endpunkten gut zu gebrauchen. |
Beispiel
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
Die folgenden Testtypen werden unterstützt:
| Typ | Beschreibung |
|---|---|
unittest |
Ergebnisse von Komponententests |
fvt |
Ergebnisse von Funktionstests (FVT = Functional verification test) |
code |
Ergebnisse der Codeabdeckung |
sonarqube |
Ergebnisse der SonarQube-Überprüfung |
vulnerabilityadvisor |
Vulnerability Advisor-Ergebnisse von IBM Vulnerability Advisor on Cloud |
cratf |
Vom Code Risk Analyzer erstellter Terraform-Bericht |
crabom |
Von Code Risk Analyzer erstellter Bericht über die Materialliste (BOM) |
cradeploy |
Vom Code Risk Analyzer erstellter Einsatzbericht |
cracve |
Von Code Risk Analyzer erstellter Schwachstellenbericht |
zapscan |
OWASP Zed Attack Proxy (ZAP) Scan-Berichte |
IBM Application Security on Cloud 1.0.0 wird nicht mehr veröffentlicht (staticsecurityscan und dynamicsecurityscan test types). Der gesamte IBM Application Security on Cloud 1.0.0 Support wird von HCL bereitgestellt.
Weitere Informationen finden Sie in der HCL-Dokumentation AppScan.
Bereitstellungsdatensatz veröffentlichen
Mit dem folgenden Befehl wird ein Bereitstellungsdatensatz in DevOps Insights veröffentlicht:
ibmcloud doi deployrecord-publish --env ENV --status STATUS --logicalappname LOGICALAPPNAME --buildnumber BUILDNUMBER --toolchainid TOOLCHAINID [--joburl JOBURL] [--appurl APPURL] [--region REGION]
| Befehlsoptionen | Erforderlich oder optional | Beschreibung |
|---|---|---|
-E, --env |
Erforderlich | Die Umgebung, in der der Pipeline-Job von der App bereitgestellt wurde. |
-S, --status |
Erforderlich | Der Bereitstellungsstatus. Zulässige Werte sind 'pass' und 'fail'. |
-L, --logicalappname |
Erforderlich | Der Name der Anwendung. |
-N, --buildnumber |
Erforderlich | Eine beliebige Zeichenfolge zur Kennzeichnung des Builds. |
-I, --toolchainid |
Erforderlich | Wenn die Umgebungsvariable TOOLCHAIN_ID gesetzt ist, ist dieses Flag optional. Wenn sowohl die Umgebungsvariable als auch das Flag angegeben werden, hat der Wert des Flags Vorrang vor dem Wert der Umgebungsvariablen. |
-A, --appurl |
Optionale | Die URL, unter der die bereitgestellte App ausgeführt wird. |
-J, --joburl |
Optionale | Die URL für die Buildprotokolle des Jobs, die von der CLI automatisch in IBM® Continuous Delivery Pipeline for IBM Cloud® festgelegt wird. |
--region |
Erforderlich | Die Region ibmcloud der Toolchain. Dieser Wert ist erforderlich, wenn private Endpunkte verwendet werden. Sie ist optional, aber im Falle von öffentlichen Endpunkten gut zu gebrauchen. |
Beispiel
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
Gates auswerten
Mit dem folgenden Befehl wird ein DevOps Insights-Gate ausgewertet:
ibmcloud doi gate-evaluate --policy POLICY --logicalappname LOGICALAPPNAME --buildnumber BUILDNUMBER --toolchainid TOOLCHAINID [--forcedecision] [--ruletype RULETYPE] [--region REGION]
Die folgenden Befehlsoptionen sind für das Auswerten von Gates verfügbar:
| Befehlsoptionen | Erforderlich oder optional | Beschreibung |
|---|---|---|
-P, --policy |
Erforderlich | Der Name der Richtlinie, die den Entscheidungen des Gate zugrunde liegt. |
-L, --logicalappname |
Erforderlich | Der Name der Anwendung. |
-N, --buildnumber |
Erforderlich | Eine beliebige Zeichenfolge zur Kennzeichnung des Builds. |
-I, --toolchainid |
Erforderlich | Wenn die Umgebungsvariable TOOLCHAIN_ID gesetzt ist, ist dieses Flag optional. Wenn sowohl die Umgebungsvariable als auch das Flag angegeben werden, hat der Wert des Flags Vorrang vor dem Wert der Umgebungsvariablen. |
-D, --forcedecision |
Optionale | Legen Sie 'true' als Wert fest, damit eine Beendigung mit einem Fehlercode erfolgt, wenn die Richtlinienauswertung fehlschlägt. Ist diese Option nicht angegeben, wird der Standardwert 'false' verwendet. |
-E, --ruletype |
Optionale | Ein zu berücksichtigender Regeltyp. Wenn Sie diese Option angeben, werden nur Regeln dieser Art im Entscheidungsfindungsprozess berücksichtigt. |
--region |
Erforderlich | Die Region ibmcloud der Toolchain. Dieser Wert ist erforderlich, wenn private Endpunkte verwendet werden. Sie ist optional, aber im Falle von öffentlichen Endpunkten gut zu gebrauchen. |
Beispiel
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
Aktualisierung von benutzerdefinierten Datensätzen und Richtlinien
Der folgende Befehl erstellt und aktualisiert benutzerdefinierte Datensätze und Richtlinien für eine Toolchain:
ibmcloud doi policies-update --file FILELOCATION --toolchainid TOOLCHAINID [--dryrun] [--region REGION]
Im Folgenden finden Sie Befehlsoptionen für die Aktualisierung von benutzerdefinierten Datensätzen und Richtlinien:
| Befehlsoptionen | Erforderlich oder optional | Beschreibung |
|---|---|---|
-F, --file |
Erforderlich | Der Speicherort der JSON-Datei, die die Liste der hinzuzufügenden oder zu aktualisierenden benutzerdefinierten Datensätze und Richtlinien enthält. Es werden sowohl absolute als auch relative Pfade akzeptiert. |
-I, --toolchainid |
Erforderlich | Wenn die Umgebungsvariable TOOLCHAIN_ID gesetzt ist, ist dieses Flag optional. Wenn sowohl die Umgebungsvariable als auch das Flag angegeben werden, hat der Wert des Flags Vorrang vor dem Wert der Umgebungsvariablen. |
-D, --dryrun |
Optionale | Die Option, nur die Änderungen zu simulieren, ohne dass Aktualisierungen vorgenommen werden. |
--region |
Erforderlich | Die Region ibmcloud der Toolchain. Dieser Wert ist erforderlich, wenn private Endpunkte verwendet werden. Sie ist optional, aber im Falle von öffentlichen Endpunkten gut zu gebrauchen. |
Beispiel
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
JSON-Dateistruktur für den Befehl updatepolicies
Eine gültige JSON-Dateistruktur enthält zwei Felder:
{
"custom_datasets": [],
"policies": []
}
- Sie können eine beliebige Anzahl von Richtlinien (und benutzerdefinierten Datensätzen) für das Array angeben.
- Wenn die angegebene Richtlinie (und der benutzerdefinierte Datensatz) für eine Toolchain existiert, wird die Richtlinie aktualisiert oder erstellt.
- Entweder das Array
custom_datasetsoderpolicieskann leer sein, oder beide können leer sein. - Die einzigen gültigen Werte für einen benutzerdefinierten Datensatz
type_of_testsindtestundcode. - Wenn ein benutzerdefinierter Datensatz für eine Toolchain existiert, kann er in den Richtlinienregeln verwendet werden, die in der JSON-Datei definiert sind. Es ist nicht immer erforderlich, den benutzerdefinierten Datensatz in der JSON-Datei zu definieren.
- Die JSON-Beispieldatei, die für den Befehl
policies-updatebereitgestellt wird, listet alle möglichen Regeltypen auf, die Sie in einer Richtlinie angeben können. Alle Felder in diesen Regeln sind Pflichtfelder. - Verwenden Sie nur eine Regel pro Datensatz.
- Das Namensfeld innerhalb einer Regel ist optional.
Beispiel-JSON-Datei für den Befehl policies-update
Diese JSON-Beispieldatei enthält zwei benutzerdefinierte Datensätze und zwei Richtlinien. Die erste Richtlinie name: "Orders" enthält alle Regeltypen, die Sie in einer Richtlinie verwenden können.
{
"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": []
}
]
}
]
}
Häufig gestellte Fragen
Hier finden Sie Antworten auf häufig gestellte Fragen zur Verwendung der CLI für DevOps Insights.
Warum schlägt die CLI mit der Meldung "Sie haben keinen Zugriff auf die Toolchain" fehl?
Die Umgebungsvariable API_KEY, mit der man sich bei IBM Cloud anmeldet, muss auf die Toolchain zugreifen können. Vergewissern Sie sich auch, dass Sie die Integration des Tools DevOps Insights zu Ihrer Toolchain hinzugefügt haben.
Die CLI wurde erfolgreich ausgeführt, warum werden die Daten nicht auf dem Dashboard angezeigt?
Stellen Sie sicher, dass die Werte der Parameter logicalappname und buildnumber, die an die CLI übergeben werden, in allen Phasen des Builds gleich sind. Vergewissern Sie sich auch, dass ein Build-Datensatz für den
Build hochgeladen wurde. Die Daten für Testdatensätze, die für ein bestimmtes Build hochgeladen werden, erscheinen nicht auf dem Dashboard ohne einen Build-Datensatz.
Die CLI kommuniziert nicht mehr mit dem Sonarqube-Server. Gibt es eine Möglichkeit, die Timeout-Zeit zu erhöhen?
Die Standard-Timeout-Dauer beträgt 60 Sekunden. Bevor Sie die DevOps Insights CLI aufrufen, setzen Sie die Umgebungsvariable IBMCLOUD_HTTP_TIMEOUT. Sein Wert ist die Anzahl der Sekunden.
export IBMCLOUD_HTTP_TIMEOUT=120
Wie kann ich feststellen, warum die CLI fehlgeschlagen ist?
Bevor Sie die DevOps Insights-CLI aufrufen, setzen Sie die IBMCLOUD_TRACE Umgebungsvariable auf true, um das Debug-Protokoll zu aktivieren.
export IBMCLOUD_TRACE=true
Beobachten Sie die API-Aufrufe und die Antworten, die im Protokoll angezeigt werden, um die genaue Fehlerursache zu ermitteln.