CLI do DevOps Insights

A CLI do IBM Cloud® DevOps Insights fornece um conjunto de comandos que você pode usar para integrar sua compilação com o DevOps Insights. Use dois tipos diferentes de comandos: Comandos de uso da CLI e comandos da CLI para integração com DevOps Insights.

DevOps Insights chegou ao fim de sua vida útil e não está mais disponível. Saiba mais

Antes de Iniciar

  • Instale a CLI do IBM Cloud. Consulte Download IBM Cloud CLI para instruções.

  • Inclua o plug-in da CLI do IBM Cloud. Execute o comando a seguir:

ibmcloud plugin install doi
  • Verifique se é possível acessar uma cadeia de ferramentas com a ferramenta DevOps Insights que está configurada para essa cadeia de ferramentas. Para obter mais informações sobre cadeias de ferramentas, consulte Criando uma cadeia de ferramentas por meio de um app.

  • Especifique a ID da cadeia de ferramentas usando um dos métodos a seguir:

    • Especifique a ID da cadeia de ferramentas como um parâmetro da CLI para o comando.
    • Defina a variável de ambiente TOOLCHAIN_ID .
    • Seu pipeline IBM Cloud® Continuous Delivery pode definir automaticamente a variável de ambiente PIPELINE_TOOLCHAIN_ID.

    A CLI precisa do valor da ID da cadeia de ferramentas. O valor da ID do conjunto de ferramentas especificado no parâmetro da CLI substitui o valor da variável de ambiente.

    O ID da cadeia de ferramentas está localizado na URL da cadeia de ferramentas que é mostrada no navegador. Se estiver usando IBM® Continuous Delivery Pipeline for IBM Cloud®, poderá definir o ID da cadeia de ferramentas para enviar os dados de compilação para uma cadeia de ferramentas diferente. Para obter mais informações, veja Agregando dados de diversas origens e uma única cadeia de ferramentas.

Login

Use esse comando para efetuar login no IBM Cloud. O API_KEY deve ter acesso à cadeia de ferramentas.

ibmcloud login --apikey API_KEY

Faça login na CLI usando um endpoint privado

Para maior controle e segurança dos seus dados ao usar a CLI, você tem a opção de usar rotas privadas para os pontos de extremidade IBM Cloud. Deve-se primeiro ativar o roteamento e o encaminhamento virtuais em sua conta para poder, em seguida, ativar o uso de terminais em serviço privados do IBM Cloud. Para obter mais informações sobre a configuração de sua conta para suportar a opção de conectividade privada, consulte Ativando o VRF e terminais em serviço.

Use o comando a seguir para fazer login em um endpoint privado por meio da CLI. O API_KEY deve ter acesso à cadeia de ferramentas.

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

Comandos de uso da CLI

DevOps Insights help

O comando a seguir exibe a lista de comandos do DevOps Insights:

 ibmcloud doi --help

Ajuda de comando do DevOps Insights

O comando a seguir exibe os detalhes das opções necessárias para um comando:

 ibmcloud doi <command> --help

Você pode passar um parâmetro --region para qualquer um dos comandos. Ao definir o valor desse parâmetro como a região ibmcloud da cadeia de ferramentas, a CLI não precisa determinar em qual região a cadeia de ferramentas está, o que a torna mais eficiente e confiável. Esse parâmetro é opcional para compatibilidade com versões anteriores.

Comandos para integração com o DevOps Insights

Ao usar a CLI para uma construção, deve-se publicar um registro de construção.

O valor dos parâmetros logicalappname e buildnumber que são passados para a CLI deve permanecer o mesmo em todas as invocações de comando.

Publicando um registro de construção

O comando a seguir publica um registro de construção para o 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 seguir estão as opções de comando para publicar um registro de construção.

Opções de comando para publicar um registro de compilação
Opções de comando Obrigatório ou opcional Descrição
-B, --branch Obrigatório A ramificação do repositório no qual a construção está sendo executada.
-R, --repositoryurl Obrigatório A URL do repositório Git.
-C, --commitid Obrigatório O ID de confirmação do Git.
-S, --status Obrigatório O status da construção. Os valores aceitáveis são: pass e fail.
-L, --logicalappname Obrigatório Nome do aplicativo.
-N, --buildnumber Obrigatório Qualquer sequência que identifique a construção.
-I, --toolchainid Obrigatório Se a variável de ambiente TOOLCHAIN_ID estiver definida, esse sinalizador será opcional. Se tanto a variável de ambiente quanto o sinalizador forem fornecidos, o valor do sinalizador substituirá o valor da variável de ambiente.
-J, --joburl Opcional A URL para os logs de construção da tarefa que é configurada automaticamente pela CLI no IBM® Continuous Delivery Pipeline for IBM Cloud®.
--region Obrigatório A região ibmcloud da cadeia de ferramentas. Esse valor é necessário ao usar endpoints privados. É opcional, mas é bom tê-lo no caso de endpoints públicos.

Exemplo

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

Publicação de um registro de teste

O comando a seguir publica um registro de teste para o 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 seguir estão as opções de comando para a publicação de registros de teste.

Opções de comando para publicar um registro de compilação
Opções de comando Obrigatório ou opcional Descrição
-F, --filelocation Obrigatório Localização dos resultados que você deseja transferir por upload. Ele pode ser um único arquivo, um diretório inteiro ou vários arquivos que correspondem a uma expressão curinga.
-T, --type Obrigatório O tipo de resultados de teste que você deseja transferir por upload.
-L, --logicalappname Obrigatório Nome do aplicativo.
-N, --buildnumber Obrigatório Qualquer sequência que identifique a construção.
-I, --toolchainid Obrigatório Se a variável de ambiente TOOLCHAIN_ID estiver definida, esse sinalizador será opcional. Se tanto a variável de ambiente quanto o sinalizador forem fornecidos, o valor do sinalizador substituirá o valor da variável de ambiente.
-U, --drilldownurl Opcional Uma URL na qual mais informações sobre os resultados de teste podem ser localizadas. Se essa URL for inválida, a opção será ignorada.
-E, --env Opcional O nome do ambiente a ser associado aos resultados de teste. Essa opção é ignorada para testes de unidade, testes de cobertura de código e varreduras de segurança estática.
-K, --sqtoken Opcional Esse comando é um token SonarQube. Válido apenas se o tipo especificado for SonarQube. Utilizado para obter mais informações do servidor SonarQube.
--tags Opcional Especifique uma lista de tags separada por vírgulas para associar a esse resultado de teste.
--region Obrigatório A região ibmcloud da cadeia de ferramentas. Esse valor é necessário ao usar endpoints privados. É opcional, mas é bom tê-lo no caso de endpoints públicos.

Exemplo

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

Os tipos de teste a seguir são suportados:

Tipos de registro de teste
Tipo Descrição
unittest Resultados de teste de unidade
fvt Resultados do teste de verificação funcional (FVT)
code Resultados de cobertura de código
sonarqube Resultados de varredura do SonarQube
vulnerabilityadvisor Os resultados do Vulnerability Advisor do IBM Vulnerability Advisor on Cloud
cratf Relatório do Terraform gerado pelo Code Risk Analyzer
crabom Relatório de lista de materiais (BOM) gerado pelo Code Risk Analyzer
cradeploy Relatório de implantação gerado pelo Code Risk Analyzer
cracve Relatório de vulnerabilidade gerado pelo Code Risk Analyzer
zapscan Relatórios de varredura do OWASP Zed Attack Proxy (ZAP)

IBM Application Security on Cloud 1.0.0 não é mais publicado (tipos de teste staticsecurityscan e dynamicsecurityscan ). Todo o suporte IBM Application Security on Cloud 1.0.0 é fornecido pela HCL. Para obter mais informações, consulte a documentação do HCL AppScan.

Publicando um registro de implementação

O comando a seguir publica um registro de implementação para o DevOps Insights:

 ibmcloud doi deployrecord-publish --env ENV --status STATUS --logicalappname LOGICALAPPNAME --buildnumber BUILDNUMBER --toolchainid TOOLCHAINID [--joburl JOBURL] [--appurl APPURL] [--region REGION]
Opções de comando para publicar um registro de implantação
Opções de comando Obrigatório ou opcional Descrição
-E, --env Obrigatório O ambiente no qual a tarefa de pipeline implementou o aplicativo.
-S, --status Obrigatório O status de implementação. Esse valor deve ser pass ou fail.
-L, --logicalappname Obrigatório Nome do aplicativo.
-N, --buildnumber Obrigatório Qualquer sequência que identifique a construção.
-I, --toolchainid Obrigatório Se a variável de ambiente TOOLCHAIN_ID estiver definida, esse sinalizador será opcional. Se tanto a variável de ambiente quanto o sinalizador forem fornecidos, o valor do sinalizador substituirá o valor da variável de ambiente.
-A, --appurl Opcional A URL na qual o aplicativo implementado está em execução.
-J, --joburl Opcional A URL para os logs de construção da tarefa configurada automaticamente pela CLI no IBM® Continuous Delivery Pipeline for IBM Cloud®.
--region Obrigatório A região ibmcloud da cadeia de ferramentas. Esse valor é necessário ao usar endpoints privados. É opcional, mas é bom tê-lo no caso de endpoints públicos.

Exemplo

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

Avaliando as portas

O comando a seguir avalia uma porta do DevOps Insights:

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

A seguir estão as opções de comando para avaliar as portas:

Opções de comando para avaliação de portões
Opções de comando Obrigatório ou opcional Descrição
-P, --policy Obrigatório O nome da política que a porta usa para tomar sua decisão.
-L, --logicalappname Obrigatório Nome do aplicativo.
-N, --buildnumber Obrigatório Qualquer sequência que identifique a construção.
-I, --toolchainid Obrigatório Se a variável de ambiente TOOLCHAIN_ID estiver definida, esse sinalizador será opcional. Se tanto a variável de ambiente quanto o sinalizador forem fornecidos, o valor do sinalizador substituirá o valor da variável de ambiente.
-D, --forcedecision Opcional Configure o valor como true para sair com um código de erro se a avaliação de política falhar. O valor será padronizado como false se essa opção não for especificada.
-E, --ruletype Opcional Um tipo de regra a ser considerado. Se você incluir essa opção, apenas as regras desse tipo serão consideradas no processo de tomada de decisão.
--region Obrigatório A região ibmcloud da cadeia de ferramentas. Esse valor é necessário ao usar endpoints privados. É opcional, mas é bom tê-lo no caso de endpoints públicos.

Exemplo

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

Atualização de políticas e conjuntos de dados personalizados

O comando a seguir cria e atualiza conjuntos de dados e políticas personalizados para uma cadeia de ferramentas:

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

Veja a seguir as opções de comando para atualizar conjuntos de dados e políticas personalizados:

Opções de comando para atualizar conjuntos de dados e políticas personalizados
Opções de comando Obrigatório ou opcional Descrição
-F, --file Obrigatório O local do arquivo JSON que contém a lista de conjuntos de dados personalizados e políticas a serem adicionadas ou atualizadas. São aceitos caminhos absolutos e relativos.
-I, --toolchainid Obrigatório Se a variável de ambiente TOOLCHAIN_ID estiver definida, esse sinalizador será opcional. Se tanto a variável de ambiente quanto o sinalizador forem fornecidos, o valor do sinalizador substituirá o valor da variável de ambiente.
-D, --dryrun Opcional A opção de simular apenas as alterações, sem atualizações.
--region Obrigatório A região ibmcloud da cadeia de ferramentas. Esse valor é necessário ao usar endpoints privados. É opcional, mas é bom tê-lo no caso de endpoints públicos.

Exemplo

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

Estrutura de arquivo JSON para o comando updatepolicies

Uma estrutura de arquivo JSON válida contém dois campos:

{
      "custom_datasets": [],
      "policies": []
}
  • Você pode especificar qualquer número de políticas (e conjuntos de dados personalizados) para a matriz.
  • Se a política especificada (e o conjunto de dados personalizado) existir para uma cadeia de ferramentas, a política será atualizada ou criada.
  • A matriz custom_datasets ou policies pode estar vazia, ou ambas podem estar vazias.
  • Os únicos valores válidos para um conjunto de dados personalizados type_of_test são test e code.
  • Se houver um conjunto de dados personalizado para uma cadeia de ferramentas, ele poderá ser usado nas regras de política definidas no arquivo JSON. Nem sempre é necessário definir o conjunto de dados personalizado no arquivo JSON.
  • O arquivo JSON de amostra fornecido para o comando policies-update lista todos os tipos de regras possíveis que você pode especificar em uma política. Todos os campos dessas regras são obrigatórios.
  • Use apenas uma regra por conjunto de dados.
  • O campo de nome em uma regra é opcional.

Exemplo de arquivo JSON para o comando policies-update

Esse arquivo JSON de amostra contém dois conjuntos de dados personalizados e duas políticas. A primeira política name: "Orders" contém todos os tipos de regras que você pode usar em uma 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": []
        }
      ]
    }
  ]
}

FAQs

Veja as respostas às perguntas mais frequentes sobre o uso da CLI do DevOps Insights.

Por que a CLI falha com a mensagem "You do not have access to the toolchain" (Você não tem acesso à cadeia de ferramentas)?

A variável de ambiente API_KEY que é usada para fazer login em IBM Cloud deve ser capaz de acessar a cadeia de ferramentas. Além disso, verifique se você adicionou a integração da ferramenta DevOps Insights à sua cadeia de ferramentas.

A CLI foi executada com êxito, mas por que os dados não são exibidos no painel?

Certifique-se de que o valor dos parâmetros logicalappname e buildnumber que são passados para a CLI sejam os mesmos em todos os estágios da compilação. Além disso, verifique se um registro de compilação foi carregado para a compilação. Os dados dos registros de teste que são carregados para uma compilação específica não aparecem no painel sem um registro de compilação.

A CLI não consegue se comunicar com o servidor Sonarqube. Existe uma maneira de aumentar o período de tempo limite?

O tempo limite padrão é de 60 segundos. Antes de chamar a CLI do DevOps Insights, defina a variável de ambiente IBMCLOUD_HTTP_TIMEOUT. Seu valor é o número de segundos.

    export IBMCLOUD_HTTP_TIMEOUT=120

Como posso determinar por que a CLI falhou?

Antes de chamar a CLI do DevOps Insights, defina a variável de ambiente IBMCLOUD_TRACE como true para ativar o log de depuração.

    export IBMCLOUD_TRACE=true

Observe as chamadas de API e as respostas mostradas no log para determinar a razão exata da falha.