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_ID Umgebungsvariable.
    • 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 für die Veröffentlichung eines Build-Records
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 für die Veröffentlichung eines Build-Records
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:

Test-Datensatztypen
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 für die Veröffentlichung eines Einsatzdatensatzes
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 für die Bewertung von Gates
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 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_datasets oder policies kann leer sein, oder beide können leer sein.
  • Die einzigen gültigen Werte für einen benutzerdefinierten Datensatz type_of_test sind test und code.
  • 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-update bereitgestellt 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.