Interface de ligne de commande DevOps Insights

Le CLI IBM Cloud® DevOps Insights fournit un ensemble de commandes que vous pouvez utiliser pour intégrer votre construction à DevOps Insights. Utilisez deux types de commandes différents : Les commandes d'utilisation de la CLI et les commandes de la CLI à intégrer à DevOps Insights.

DevOps Insights Ce produit a atteint la fin de son cycle de vie et n'est plus disponible. En savoir plus

Avant de commencer

  • Installez l'interface de ligne de commande IBM Cloud. Pour plus d'informations, voir Download IBM Cloud CLI.

  • Ajoutez le plug-in CLI d' IBM Cloud. Exécutez la commande suivante :

ibmcloud plugin install doi
  • Assurez-vous que vous pouvez accéder à une chaîne d'outils avec l'outil DevOps Insights qui est configuré pour cette chaîne d'outils. Pour plus d'informations sur les chaînes d'outils, voir Création d'une chaîne d'outils à partir d'une application.

  • Spécifiez l'ID de la chaîne d'outils en utilisant l'une des méthodes suivantes :

    • Spécifiez l'ID de la chaîne d'outils en tant que paramètre CLI de la commande.
    • Définissez la variable d'environnement TOOLCHAIN_ID.
    • Votre pipeline IBM Cloud® Continuous Delivery peut définir automatiquement la variable d'environnement PIPELINE_TOOLCHAIN_ID.

    Le CLI a besoin de la valeur de l'ID de la chaîne d'outils. La valeur de l'ID de la chaîne d'outils spécifiée dans le paramètre CLI remplace la valeur de la variable d'environnement.

    L'ID de chaîne d'outils se trouve dans l'URL de la chaîne d'outils qui est affichée dans le navigateur. Si vous utilisez IBM® Continuous Delivery Pipeline for IBM Cloud®, vous pouvez définir l'ID de la chaîne d'outils pour envoyer vos données de construction à une chaîne d'outils différente. Pour plus d'informations, voir Agrégation de données issues de multiples sources dans une seule chaîne d'outils.

Connexion

Connectez-vous à IBM Cloud à l'aide de la commande ci-dessous. La clé d'API (API_KEY) doit avoir accès à la chaîne d'outils.

ibmcloud login --apikey API_KEY

Se connecter à l'interface CLI à l'aide d'un point de terminaison privé

Pour améliorer le contrôle et la sécurité de vos données lors de l'utilisation de CLI, vous avez la possibilité d'utiliser des routes privées vers les points d'extrémité IBM Cloud. Vous devez d'abord activer le routage et le transfert virtuels dans votre compte, puis vous pouvez activer l'utilisation des noeuds finaux de service privés IBM Cloud. Pour plus d'informations sur la configuration de votre compte pour prendre en charge l'option de connectivité privée, voir Activation de VRF et de noeuds finaux de service.

Utilisez la commande suivante pour vous connecter à un point de terminaison privé à l'aide de l'interface de ligne de commande (CLI). La clé d'API (API_KEY) doit avoir accès à la chaîne d'outils.

ibmcloud login -a private.cloud.ibm.com --apikey API_KEY

Commandes liées à l'utilisation de l'interface de ligne de commande

Aide DevOps Insights

La commande suivante affiche la liste des commandes DevOps Insights :

 ibmcloud doi --help

Aide sur les commandes DevOps Insights

La commande suivante affiche les détails des options requises pour une commande :

 ibmcloud doi <command> --help

Vous pouvez passer un paramètre --region à n'importe quelle commande. En fixant la valeur de ce paramètre à la région ibmcloud de la chaîne d'outils, la CLI n'a pas besoin de déterminer dans quelle région se trouve la chaîne d'outils, ce qui la rend plus efficace et plus fiable. Ce paramètre est facultatif pour des raisons de compatibilité avec les versions antérieures.

Commandes d'intégration à DevOps Insights

Lorsque vous utilisez l'interface de ligne de commande pour une génération, vous devez publier un enregistrement de génération.

La valeur des paramètres logicalappname et buildnumber qui sont transmis à la CLI doit rester la même pour toutes les invocations de la commande.

Publication d'un enregistrement de génération

La commande suivante publie un enregistrement de génération sur DevOps Insights :

 ibmcloud doi buildrecord-publish --branch BRANCH --repositoryurl REPOSITORYURL --commitid COMMITID --status STATUS --logicalappname LOGICALAPPNAME --buildnumber BUILDNUMBER --toolchainid TOOLCHAINID [--joburl JOBURL] [--region REGION]

Les options de commande pour la publication d'un enregistrement de génération sont les suivantes :

Options de commande pour la publication d'un enregistrement de construction
Options de commande Requise ou facultative Description
-B, --branch Obligatoire Branche du référentiel sur laquelle la génération est effectuée.
-R, --repositoryurl Obligatoire URL du référentiel Git.
-C, --commitid Obligatoire ID de validation Git.
-S, --status Obligatoire Statut de la génération. Valeurs admises : pass et fail.
-L, --logicalappname Obligatoire Nom de l'application.
-N, --buildnumber Obligatoire Chaîne qui identifie la génération.
-I, --toolchainid Obligatoire Si la variable d'environnement TOOLCHAIN_ID est définie, cet indicateur est facultatif. Si la variable d'environnement et l'indicateur sont tous deux fournis, la valeur de l'indicateur prévaut sur celle de la variable d'environnement.
-J, --joburl Facultatif URL des journaux de génération du travail automatiquement définie par l'interface de ligne de commande dans le pipeline IBM® Continuous Delivery Pipeline for IBM Cloud®.
--region Obligatoire La région ibmcloud de la chaîne d'outils. Cette valeur est requise lors de l'utilisation de points d'extrémité privés. Elle est facultative mais utile dans le cas de points d'extrémité publics.

Exemple

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

Publication d'un enregistrement de test

La commande suivante publie un enregistrement de test sur 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]

Les options de commande pour la publication d'un enregistrement de test sont les suivantes :

Options de commande pour la publication d'un enregistrement de construction
Options de commande Requise ou facultative Description
-F, --filelocation Obligatoire Emplacement des résultats que vous voulez télécharger. Il peut s'agir d'un unique fichier, de l'intégralité d'un répertoire ou de plusieurs fichiers qui correspondent à une expression générique.
-T, --type Obligatoire Type de résultats de test que vous voulez télécharger.
-L, --logicalappname Obligatoire Nom de l'application.
-N, --buildnumber Obligatoire Chaîne qui identifie la génération.
-I, --toolchainid Obligatoire Si la variable d'environnement TOOLCHAIN_ID est définie, cet indicateur est facultatif. Si la variable d'environnement et l'indicateur sont tous deux fournis, la valeur de l'indicateur prévaut sur celle de la variable d'environnement.
-U, --drilldownurl Facultatif URL d'accès à d'autres informations relatives aux résultats de test. Si cette URL n'est pas valide, l'option est ignorée.
-E, --env Facultatif Nom de l'environnement à associer aux résultats de test. Cette option est ignorée pour les tests d'unité, les tests de couverture de code et les analyses de sécurité statiques.
-K, --sqtoken Facultatif Cette commande est un jeton SonarQube. Valide uniquement si le type indiqué est SonarQube. Permet d'extraire plus d'informations du serveur SonarQube.
--tags Facultatif Spécifiez une liste de balises séparées par des virgules à associer à ce résultat de test.
--region Obligatoire La région ibmcloud de la chaîne d'outils. Cette valeur est requise lors de l'utilisation de points d'extrémité privés. Elle est facultative mais utile dans le cas de points d'extrémité publics.

Exemple

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

Les types de test suivants sont pris en charge :

Types d'enregistrements test
Type Description
unittest Résultats de test d'unité
fvt Résultats de test fonctionnel de vérification
code Résultats de couverture de code
sonarqube Résultats d'analyse SonarQube
vulnerabilityadvisor Résultats Vulnerability Advisor issus d'IBM Vulnerability Advisor on Cloud
cratf Rapport Terraform généré par Code Risk Analyzer
crabom Rapport sur la nomenclature généré par Code Risk Analyzer
cradeploy Rapport de déploiement généré par Code Risk Analyzer
cracve Rapport de vulnérabilité généré par Code Risk Analyzer
zapscan Rapports d'analyse OWASP Zed Attack Proxy (ZAP)

IBM Application Security on Cloud 1.0.0 n'est plus publié (types de tests staticsecurityscan et dynamicsecurityscan ). Toute l'assistance IBM Application Security on Cloud 1.0.0 est fournie par HCL. Pour plus d'informations, voir la documentation HCL AppScan.

Publication d'un enregistrement de déploiement

La commande suivante publie un enregistrement de deployment sur DevOps Insights :

 ibmcloud doi deployrecord-publish --env ENV --status STATUS --logicalappname LOGICALAPPNAME --buildnumber BUILDNUMBER --toolchainid TOOLCHAINID [--joburl JOBURL] [--appurl APPURL] [--region REGION]
Options de commande pour la publication d'un enregistrement de déploiement
Options de commande Requise ou facultative Description
-E, --env Obligatoire Environnement dans lequel le travail de pipeline a déployé l'application.
-S, --status Obligatoire Statut du déploiement. Cette valeur doit être pass ou fail.
-L, --logicalappname Obligatoire Nom de l'application.
-N, --buildnumber Obligatoire Chaîne qui identifie la génération.
-I, --toolchainid Obligatoire Si la variable d'environnement TOOLCHAIN_ID est définie, cet indicateur est facultatif. Si la variable d'environnement et l'indicateur sont tous deux fournis, la valeur de l'indicateur prévaut sur celle de la variable d'environnement.
-A, --appurl Facultatif URL où s'exécute l'application déployée.
-J, --joburl Facultatif URL des journaux de génération du travail automatiquement définie par l'interface de ligne de commande dans le pipeline IBM® Continuous Delivery Pipeline for IBM Cloud®.
--region Obligatoire La région ibmcloud de la chaîne d'outils. Cette valeur est requise lors de l'utilisation de points d'extrémité privés. Elle est facultative mais utile dans le cas de points d'extrémité publics.

Exemple

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

Evaluation des jalons

La commande suivante évalue un jalon DevOps Insights :

 ibmcloud doi gate-evaluate --policy POLICY --logicalappname LOGICALAPPNAME --buildnumber BUILDNUMBER --toolchainid TOOLCHAINID [--forcedecision] [--ruletype RULETYPE] [--region REGION]

Les options de commande pour l'évaluation des jalons sont les suivantes :

Options de commande pour l'évaluation des portails
Options de commande Requise ou facultative Description
-P, --policy Obligatoire Nom de la politique que le jalon utilise pour prendre sa décision.
-L, --logicalappname Obligatoire Nom de l'application.
-N, --buildnumber Obligatoire Chaîne qui identifie la génération.
-I, --toolchainid Obligatoire Si la variable d'environnement TOOLCHAIN_ID est définie, cet indicateur est facultatif. Si la variable d'environnement et l'indicateur sont tous deux fournis, la valeur de l'indicateur prévaut sur celle de la variable d'environnement.
-D, --forcedecision Facultatif Définissez sa valeur sur true pour quitter avec un code d'erreur en cas d'échec d'évaluation de la politique. La valeur par défaut est false si cette option n'est pas spécifiée.
-E, --ruletype Facultatif Type de règle à prendre en compte. Si vous incluez cette option, seules les règles de ce type sont prises en compte dans le processus de prise de décision.
--region Obligatoire La région ibmcloud de la chaîne d'outils. Cette valeur est requise lors de l'utilisation de points d'extrémité privés. Elle est facultative mais utile dans le cas de points d'extrémité publics.

Exemple

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

Mise à jour des ensembles de données et des politiques personnalisées

La commande suivante permet de créer et de mettre à jour des ensembles de données et des stratégies personnalisés pour une chaîne d'outils :

 ibmcloud doi policies-update --file FILELOCATION --toolchainid TOOLCHAINID [--dryrun] [--region REGION]

Les options de commande suivantes permettent de mettre à jour les ensembles de données et les stratégies personnalisés :

Options de commande pour la mise à jour des ensembles de données et des politiques personnalisées
Options de commande Requise ou facultative Description
-F, --file Obligatoire Emplacement du fichier JSON contenant la liste des ensembles de données personnalisés et des politiques à ajouter ou à mettre à jour. Les chemins d'accès absolus et relatifs sont tous deux acceptés.
-I, --toolchainid Obligatoire Si la variable d'environnement TOOLCHAIN_ID est définie, cet indicateur est facultatif. Si la variable d'environnement et l'indicateur sont tous deux fournis, la valeur de l'indicateur prévaut sur celle de la variable d'environnement.
-D, --dryrun Facultatif L'option de simuler uniquement les changements, sans mise à jour.
--region Obligatoire La région ibmcloud de la chaîne d'outils. Cette valeur est requise lors de l'utilisation de points d'extrémité privés. Elle est facultative mais utile dans le cas de points d'extrémité publics.

Exemple

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

Structure de fichier JSON pour la commande updatepolicies

La structure d'un fichier JSON valide contient deux champs :

{
      "custom_datasets": [],
      "policies": []
}
  • Vous pouvez spécifier un nombre quelconque de politiques (et d'ensembles de données personnalisés) pour le tableau.
  • Si la politique spécifiée (et l'ensemble de données personnalisées) existe pour une chaîne d'outils, la politique est mise à jour ou créée.
  • Le tableau custom_datasets ou policies peut être vide, ou les deux peuvent être vides.
  • Les seules valeurs valables pour un ensemble de données personnalisées type_of_test sont test et code.
  • Si un ensemble de données personnalisé existe pour une chaîne d'outils, il peut être utilisé dans les règles définies dans le fichier JSON. Il n'est pas toujours nécessaire de définir l'ensemble de données personnalisé dans le fichier JSON.
  • L'exemple de fichier JSON fourni pour la commande policies-update répertorie tous les types de règles possibles que vous pouvez spécifier dans une politique. Tous les champs de ces règles sont obligatoires.
  • N'utilisez qu'une seule règle par ensemble de données.
  • Le champ "nom" d'une règle est facultatif.

Exemple de fichier JSON pour la commande policies-update

Cet exemple de fichier JSON contient deux ensembles de données personnalisés et deux politiques. La première politique name: "Orders" contient tous les types de règles que vous pouvez utiliser dans une politique.

{
  "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": []
        }
      ]
    }
  ]
}

Foire aux questions

Obtenez des réponses aux questions fréquemment posées concernant l'utilisation de l'interface de ligne de commande (CLI) d' DevOps Insights.

Pourquoi le CLI échoue-t-il avec le message "You do not have access to the toolchain" (Vous n'avez pas accès à la chaîne d'outils)?

La variable d'environnement API_KEY utilisée pour se connecter à IBM Cloud doit pouvoir accéder à la chaîne d'outils. Vérifiez également que vous avez ajouté l'intégration de l'outil DevOps Insights à votre chaîne d'outils.

Le CLI a été exécuté avec succès, mais pourquoi les données ne s'affichent-elles pas sur le tableau de bord?

Assurez-vous que la valeur des paramètres logicalappname et buildnumber qui sont transmis à l'ITC est la même pour toutes les étapes de la construction. Vérifiez également qu'un enregistrement de construction est téléchargé pour la construction. Les données des enregistrements de test qui sont téléchargés pour une version spécifique n'apparaissent pas sur le tableau de bord sans un enregistrement de version.

Le CLI ne parvient pas à communiquer avec le serveur Sonarqube, existe-t-il un moyen d'augmenter le délai d'attente?

Le délai d'expiration par défaut est de 60 secondes. Avant d'appeler l'interface de programmation DevOps Insights, définissez la variable d'environnement IBMCLOUD_HTTP_TIMEOUT. Sa valeur est le nombre de secondes.

    export IBMCLOUD_HTTP_TIMEOUT=120

Comment puis-je déterminer la raison de l'échec de l'interface de ligne de commande ?

Avant d’appeler l’interface CLI d’ DevOps Insights, définissez la variable d’environnement IBMCLOUD_TRACE sur true pour activer le journal de débogage.

    export IBMCLOUD_TRACE=true

Observez les appels d'API et les réponses affichées dans le journal pour déterminer la raison exacte de l'échec.