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 | 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 | 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:
| 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 | 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 | 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 | 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_datasetsoupoliciespode estar vazia, ou ambas podem estar vazias. - Os únicos valores válidos para um conjunto de dados personalizados
type_of_testsãotestecode. - 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-updatelista 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.