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 | 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 | 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 :
| 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 | 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 | 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 | 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_datasetsoupoliciespeut être vide, ou les deux peuvent être vides. - Les seules valeurs valables pour un ensemble de données personnalisées
type_of_testsonttestetcode. - 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-updateré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.