CLI de DevOps Insights

La CLI de IBM Cloud® DevOps Insights proporciona un conjunto de comandos que puede utilizar para integrar su compilación con DevOps Insights. Utiliza dos tipos diferentes de comandos : Comandos de uso de la CLI y comandos de la CLI para integrarse con DevOps Insights.

DevOps Insights Ha llegado al final de su vida útil y ya no está disponible. Más información

Antes de empezar

  • Instale la CLI de IBM Cloud. Consulte Descargar CLI de IBM Cloud para obtener instrucciones.

  • Añade el complemento de la CLI de IBM Cloud. Ejecute el mandato siguiente:

ibmcloud plugin install doi
  • Asegúrese de que puede acceder a una cadena de herramientas con la herramienta DevOps Insights configurada para esa cadena de herramientas. Para obtener más información sobre las cadenas de herramientas, consulte Creación de una cadena de herramientas a partir de una app.

  • Especifique el ID de la cadena de herramientas utilizando uno de los siguientes métodos:

    • Especifique el ID de la cadena de herramientas como parámetro CLI del comando.
    • Configure la variable de entorno TOOLCHAIN_ID.
    • Es posible que su canal IBM Cloud® Continuous Delivery establezca automáticamente la variable de entorno PIPELINE_TOOLCHAIN_ID.

    La CLI necesita el valor del ID de la cadena de herramientas. El valor del ID de la cadena de herramientas que se especifica en el parámetro CLI anula el valor de la variable de entorno.

    El ID de la cadena de herramientas se encuentra en el URL de la cadena de herramientas que se muestra en el navegador. Si está utilizando IBM® Continuous Delivery Pipeline for IBM Cloud®, puede establecer el ID de la cadena de herramientas para enviar sus datos de compilación a una cadena de herramientas diferente. Para obtener más información, consulte Agregación de datos procedentes de diversos orígenes en una sola cadena de herramientas.

Inicio de sesión

Utilice este mandato para iniciar una sesión en IBM Cloud. API_KEY debe tener acceso a la cadena de herramientas.

ibmcloud login --apikey API_KEY

Inicia sesión en la CLI con un punto de conexión privado

Para mejorar el control y la seguridad de sus datos cuando utilice CLI, tiene la opción de utilizar rutas privadas a los puntos finales de IBM Cloud. En primer lugar, debe habilitar el direccionamiento y el reenvío virtuales en su cuenta y, a continuación, puede habilitar el uso de puntos finales de servicio privado de IBM Cloud. Para obtener más información sobre la configuración de la cuenta para dar soporte a la opción de conectividad privada, consulte Habilitación de puntos finales de VRF y de servicio.

Utiliza el siguiente comando para iniciar sesión en un punto de conexión privado mediante la CLI. API_KEY debe tener acceso a la cadena de herramientas.

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

Mandatos de uso de la CLI

Ayuda de DevOps Insights

El siguiente mandato muestra la lista de mandatos de DevOps Insights:

 ibmcloud doi --help

Ayuda para el mandato de DevOps Insights

El siguiente comando muestra los detalles de los parámetros que se requieren para un comando :

 ibmcloud doi <command> --help

Puede pasar un parámetro --region a cualquiera de los comandos. Al establecer el valor de este parámetro en la región ibmcloud de la cadena de herramientas, la CLI no necesita determinar en qué región se encuentra la cadena de herramientas, lo que la hace más eficiente y fiable. Este parámetro es opcional por compatibilidad con versiones anteriores.

Mandatos para integrar con DevOps Insights

Cuando utilice la CLI para una compilación, debe publicar un registro de compilación.

El valor de los parámetros logicalappname y buildnumber que se pasan a la CLI debe seguir siendo el mismo en todas las invocaciones de comandos.

Publicación de un registro de compilaciones

El mandato siguiente publica un registro de compilación en DevOps Insights:

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

A continuación encontrará las opciones de mandatos para publicar un registro de compilación.

Opciones de comando para publicar un registro de compilación
Opciones de mandato Obligatoria u opcional Descripción
-B, --branch Obligatorio La rama del repositorio en la que se lleva a cabo la compilación.
-R, --repositoryurl Obligatorio URL del repositorio Git.
-C, --commitid Obligatorio El ID de confirmación de Git.
-S, --status Obligatorio El estado de la compilación. Valores aceptables: pass y fail.
-L, --logicalappname Obligatorio Nombre de la aplicación.
-N, --buildnumber Obligatorio Cualquier serie que identifique la compilación.
-I, --toolchainid Obligatorio Si la variable de entorno TOOLCHAIN_ID está activada, esta bandera es opcional. Si se proporcionan tanto la variable de entorno como la bandera, el valor de la bandera anula el valor de la variable de entorno.
-J, --joburl Opcional El URL a los registros de compilación del trabajo que se ha establecido automáticamente mediante la CLI en IBM® Continuous Delivery Pipeline for IBM Cloud®.
--region Obligatorio La región ibmcloud de la cadena de herramientas. Este valor es necesario cuando se utilizan endpoints privados. Es opcional pero es bueno tenerlo en caso de puntos finales públicos.

Ejemplo

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

Publicación de un registro de prueba

El mandato siguiente publica un registro de pruebas en 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]

A continuación encontrará las opciones de mandatos para publicar registros de pruebas.

Opciones de comando para publicar un registro de compilación
Opciones de mandato Obligatoria u opcional Descripción
-F, --filelocation Obligatorio La ubicación de los resultados donde desea realizar la carga. Puede ser un solo archivo, un directorio completo o varios archivos que coincidan con una expresión comodín.
-T, --type Obligatorio El tipo de resultados de pruebas que desea cargar.
-L, --logicalappname Obligatorio Nombre de la aplicación.
-N, --buildnumber Obligatorio Cualquier serie que identifique la compilación.
-I, --toolchainid Obligatorio Si la variable de entorno TOOLCHAIN_ID está activada, esta bandera es opcional. Si se proporcionan tanto la variable de entorno como la bandera, el valor de la bandera anula el valor de la variable de entorno.
-U, --drilldownurl Opcional Un URL en el que encontrar más información sobre los resultados de la prueba. Si este URL no es válido, la opción se pasa por alto.
-E, --env Opcional El nombre del entorno que se va a asociar a los resultados de la prueba. Esta opción se pasa por alto para pruebas de unidad, pruebas de cobertura de código y exploraciones de seguridad estáticas.
-K, --sqtoken Opcional Este mandato es una señal de SonarQube. Solamente es válido si el tipo especificado es SonarQube. Se utiliza para extraer más información del servidor de SonarQube.
--tags Opcional Especifique una lista separada por comas de etiquetas para asociar con este resultado de la prueba.
--region Obligatorio La región ibmcloud de la cadena de herramientas. Este valor es necesario cuando se utilizan endpoints privados. Es opcional pero es bueno tenerlo en caso de puntos finales públicos.

Ejemplo

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

Están permitidos los siguientes tipos de pruebas:

Tipos de registros de prueba
Tipo Descripción
unittest Resultados de prueba de unidad
fvt Resultados de prueba de verificación funcional (FVT)
code Resultados de cobertura de código
sonarqube Resultados de exploración de SonarQube
vulnerabilityadvisor Resultados de Vulnerability Advisor procedentes de IBM Vulnerability Advisor on Cloud
cratf Informe Terraform generado por Code Risk Analyzer
crabom Informe de lista de materiales generado por Code Risk Analyzer
cradeploy Informe de implantación generado por Code Risk Analyzer
cracve Informe de vulnerabilidad generado por Code Risk Analyzer
zapscan Informes de análisis de OWASP Zed Attack Proxy (ZAP)

IBM Application Security on Cloud 1.0.0 ya no se publica (staticsecurityscan y dynamicsecurityscan tipos de prueba). Todo el soporte de IBM Application Security on Cloud 1.0.0 es proporcionado por HCL. Para más información, consulte la documentación de HCL AppScan.

Publicación de un registro de despliegue

El mandato siguiente publica un registro de despliegue en DevOps Insights:

 ibmcloud doi deployrecord-publish --env ENV --status STATUS --logicalappname LOGICALAPPNAME --buildnumber BUILDNUMBER --toolchainid TOOLCHAINID [--joburl JOBURL] [--appurl APPURL] [--region REGION]
Opciones de comando para publicar un registro de despliegue
Opciones de mandato Obligatoria u opcional Descripción
-E, --env Obligatorio El entorno en el que el trabajo del conducto ha desplegado la app.
-S, --status Obligatorio El estado del despliegue. Los valores válidos son pass o fail.
-L, --logicalappname Obligatorio Nombre de la aplicación.
-N, --buildnumber Obligatorio Cualquier serie que identifique la compilación.
-I, --toolchainid Obligatorio Si la variable de entorno TOOLCHAIN_ID está activada, esta bandera es opcional. Si se proporcionan tanto la variable de entorno como la bandera, el valor de la bandera anula el valor de la variable de entorno.
-A, --appurl Opcional El URL en el que se ejecuta la app desplegada.
-J, --joburl Opcional El URL a los registros de compilación del trabajo que se ha establecido automáticamente mediante la CLI en IBM® Continuous Delivery Pipeline for IBM Cloud®.
--region Obligatorio La región ibmcloud de la cadena de herramientas. Este valor es necesario cuando se utilizan endpoints privados. Es opcional pero es bueno tenerlo en caso de puntos finales públicos.

Ejemplo

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

Evaluación de puertas

El siguiente mandato evalúa una puerta de DevOps Insights:

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

Estas son las opciones de mandatos para evaluar puertas:

Opciones de mando para evaluar las puertas
Opciones de mandato Obligatoria u opcional Descripción
-P, --policy Obligatorio El nombre de la política que utiliza la puerta para tomar su decisión.
-L, --logicalappname Obligatorio Nombre de la aplicación.
-N, --buildnumber Obligatorio Cualquier serie que identifique la compilación.
-I, --toolchainid Obligatorio Si la variable de entorno TOOLCHAIN_ID está activada, esta bandera es opcional. Si se proporcionan tanto la variable de entorno como la bandera, el valor de la bandera anula el valor de la variable de entorno.
-D, --forcedecision Opcional Se establece el valor en true para salir con un código de error si falla la evaluación de la política. El valor predeterminado es false si no se especifica esta opción.
-E, --ruletype Opcional Un tipo de regla a considerar. Si incluye esta opción, solo se tienen en cuenta las reglas de este tipo en el proceso de toma de decisiones.
--region Obligatorio La región ibmcloud de la cadena de herramientas. Este valor es necesario cuando se utilizan endpoints privados. Es opcional pero es bueno tenerlo en caso de puntos finales públicos.

Ejemplo

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

Actualización de conjuntos de datos y políticas personalizados

El siguiente comando crea y actualiza conjuntos de datos personalizados y políticas para una cadena de herramientas:

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

A continuación se indican las opciones de comandos para actualizar conjuntos de datos y políticas personalizados:

Opciones de comandos para actualizar conjuntos de datos y políticas personalizados
Opciones de mandato Obligatoria u opcional Descripción
-F, --file Obligatorio La ubicación del archivo JSON que contiene la lista de conjuntos de datos personalizados y políticas para añadir o actualizar. Se aceptan tanto rutas absolutas como relativas.
-I, --toolchainid Obligatorio Si la variable de entorno TOOLCHAIN_ID está activada, esta bandera es opcional. Si se proporcionan tanto la variable de entorno como la bandera, el valor de la bandera anula el valor de la variable de entorno.
-D, --dryrun Opcional La opción de simular sólo los cambios, sin actualizaciones.
--region Obligatorio La región ibmcloud de la cadena de herramientas. Este valor es necesario cuando se utilizan endpoints privados. Es opcional pero es bueno tenerlo en caso de puntos finales públicos.

Ejemplo

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

Estructura del archivo JSON para el comando updatepolicies

Una estructura de archivo JSON válida contiene dos campos:

{
      "custom_datasets": [],
      "policies": []
}
  • Puede especificar cualquier número de políticas (y conjuntos de datos personalizados) para la matriz.
  • Si la política especificada (y el conjunto de datos personalizados) existe para una cadena de herramientas, la política se actualiza o se crea.
  • Las matrices custom_datasets o policies pueden estar vacías, o ambas.
  • Los únicos valores válidos para un conjunto de datos personalizados type_of_test son test y code.
  • Si existe un conjunto de datos personalizado para una cadena de herramientas, puede utilizarse en las reglas de política que se definen en el archivo JSON. No siempre es necesario definir el conjunto de datos personalizado dentro del archivo JSON.
  • El archivo JSON de ejemplo que se proporciona para el comando policies-update enumera todos los tipos de reglas posibles que se pueden especificar en una política. Todos los campos de estas reglas son obligatorios.
  • Utilice sólo una regla por conjunto de datos.
  • El campo de nombre dentro de una regla es opcional.

Ejemplo de archivo JSON para el comando policies-update

Este archivo JSON de ejemplo contiene dos conjuntos de datos personalizados y dos políticas. La primera política name: "Orders" contiene todos los tipos de reglas que puede utilizar dentro de una política.

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

Preguntas frecuentes

Encuentra respuestas a las preguntas más frecuentes sobre el uso de la CLI de DevOps Insights.

¿Por qué falla la CLI con el mensaje "No tiene acceso a la cadena de herramientas"?

La variable de entorno API_KEY que se utiliza para iniciar sesión en IBM Cloud debe poder acceder a la cadena de herramientas. Compruebe también que ha añadido la integración de la herramienta DevOps Insights a su cadena de herramientas.

La CLI se ha ejecutado correctamente, ¿por qué no aparecen los datos en el panel de control?

Asegúrese de que el valor de los parámetros logicalappname y buildnumber que se pasan a la CLI son los mismos en todas las etapas de la compilación. Compruebe también que se ha cargado un registro de construcción para la construcción. Los datos de los registros de pruebas que se cargan para una compilación específica no aparecen en el panel sin un registro de compilación.

El CLI se queda sin comunicación con el servidor Sonarqube, ¿hay alguna forma de aumentar el tiempo de espera?

El tiempo de espera predeterminado es de 60 segundos. Antes de llamar a la CLI DevOps Insights, establezca la variable de entorno IBMCLOUD_HTTP_TIMEOUT. Su valor es el número de segundos.

    export IBMCLOUD_HTTP_TIMEOUT=120

¿Cómo puedo determinar por qué ha fallado la CLI?

Antes de llamar a la CLI de DevOps Insights, configura la variable de entorno IBMCLOUD_TRACE en true para activar el registro de depuración.

    export IBMCLOUD_TRACE=true

Observe las llamadas de API y las respuestas que se muestran en el registro para determinar la razón exacta del error.