Como integrar minhas próprias ferramentas de compilação, teste e implantação com o Code Stream

Como administrador ou desenvolvedor de DevOps, é possível criar scripts personalizados que estendem o recurso do Code Stream.

Com o script, é possível integrar o Code Stream às suas próprias ferramentas de integração contínua (IC) e entrega contínua (EC) e APIs que compilam, testam e implantam os aplicativos. Os scripts personalizados são especialmente úteis se as APIs do aplicativo não forem expostas publicamente.

O script personalizado pode fazer quase tudo o que é necessário para que as ferramentas de compilação, teste e implantação sejam integradas ao Code Stream. Por exemplo, ele pode trabalhar com o espaço de trabalho do pipeline para permitir tarefas de integração contínua que compilam e testam o aplicativo e tarefas de entrega contínua que implantam o aplicativo. Ele pode enviar uma mensagem para o Slack quando um pipeline é concluído e muito mais.

O espaço de trabalho do pipeline do Code Stream é compatível com o Docker e o Kubernetes para tarefas de integração contínua e personalizadas.

Para obter mais informações sobre a configuração do espaço de trabalho, consulte Como configurar o espaço de trabalho do pipeline.

Escreva o script personalizado em um dos idiomas compatíveis. No script, inclua a lógica de negócios e defina entradas e saídas. Os tipos de saída podem incluir número, cadeia de caracteres, texto e senha. Você pode criar várias versões de um script personalizado com diferentes lógicas de negócios, entradas e saídas.

Os scripts criados residem na instância do Code Stream. Você pode importar o código YAML para criar uma integração personalizada ou exportar seu script como um arquivo YAML a ser usado em outra instância do Code Stream.

Você instrui o pipeline a executar uma versão lançada do seu script em uma tarefa personalizada. Se você tiver várias versões laçadas, poderá definir uma delas como a mais recente, para que ela apareça com latest --> quando a tarefa personalizada for selecionada.

Quando um pipeline usar uma integração personalizada, se você tentar excluir a integração personalizada, uma mensagem de erro será exibida e indicará que não é possível excluí-la.

A exclusão de uma integração personalizada remove todas as versões do seu script personalizado. Se você tiver um pipeline existente com uma tarefa personalizada que usa qualquer versão do script, esse pipeline falhará. Para garantir que os pipelines existentes não falhem, você poderá reprovar e retirar a versão do script que não deseja mais usar. Se nenhum pipeline estiver usando essa versão, você poderá excluí-la.

Tabela 1. O que fazer após escrever o script personalizado
O que fazer...	Mais informações sobre esta ação...
Adicione uma tarefa personalizada ao pipeline.	A tarefa personalizada: É executada no mesmo contêiner de outras tarefas de IC no pipeline. Inclui as variáveis de entrada e saída que o script preenche antes que o pipeline execute a tarefa personalizada. Oferece suporte a vários tipos de dados e vários tipos de metadados definidos como entradas e saídas no script.
Selecione o script na tarefa personalizada.	Declare as propriedades de entrada e saída no script.
Salve seu pipeline e, em seguida, ative-o e execute-o.	Quando o pipeline for executado, a tarefa personalizada chamará a versão do script especificada e executará a lógica de negócios nele, que integra sua ferramenta de compilação, teste e implantação ao Code Stream.
Após a execução do pipeline, observe as execuções.	Verifique se o pipeline gerou os resultados esperados.

Quando você usa uma tarefa personalizada que chama uma versão de integração personalizada, é possível incluir variáveis de ambiente personalizadas como pares de nome/valor na guia Espaço de Trabalho do pipeline. Quando a imagem do construtor cria o contêiner de espaço de trabalho que executa a tarefa de CI e implanta a sua imagem, o Code Stream transmite as variáveis de ambiente para esse contêiner.

Por exemplo, quando a sua instância do Code Stream requer um proxy Web e você usa um host do Docker para criar um contêiner para uma integração personalizada, o Code Stream executa o pipeline e transmite as variáveis de configuração do proxy Web para esse contêiner.

Tabela 2. Exemplo de pares de nome/valor de variáveis de ambiente
Nome	Valor
HTTPS_PROXY	http://10.0.0.255:1234
https_proxy	http://10.0.0.255:1234
NO_PROXY	10.0.0.32, *.dept.vsphere.local
no_proxy	10.0.0.32, *.dept.vsphere.local
HTTP_PROXY	http://10.0.0.254:1234
http_proxy	http://10.0.0.254:1234
PATH	/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

Os pares de nome/valor aparecem na interface do usuário da seguinte maneira:

O Code Stream transmite as variáveis de ambiente ao contêiner criado pela imagem do construtor.

Este exemplo cria uma integração personalizada que conecta o Code Stream à instância do Slack e publica uma mensagem em um canal do Slack.

Pré-requisitos

Para escrever seu script personalizado, verifique se você tem uma destas linguagens: Python 2, Python 3, Node.js ou qualquer uma das linguagens de shell: Bash, sh ou zsh.
Gere uma imagem de contêiner usando o Node.js instalado ou o tempo de execução do Python.

Procedimento

Crie a integração personalizada.

Clique em Integrações Personalizadas > Novo e insira um nome relevante.
Selecione o ambiente de tempo de execução preferencial.
Clique em Criar.
Seu script é aberto e exibe o código, que inclui o ambiente de tempo de execução necessário. Por exemplo, runtime: "nodejs". O script deve incluir o tempo de execução, utilizado pela imagem do compilador, para que a tarefa personalizada adicionada ao pipeline seja bem-sucedida quando o pipeline for executado. Caso contrário, a tarefa personalizada falhará.

As principais áreas do YAML de integração personalizada incluem o tempo de execução, código, propriedades de entrada e propriedades de saída. Esse procedimento explica vários tipos e sintaxes.


Chaves de YAML de integração personalizada	Descrição
tempo de execução	Ambiente do tempo de execução da tarefa em que o Code Stream executa o código, que pode ser uma dessas cadeias de caracteres que não diferenciam maiúsculas de minúsculas: nodejs python2 python3 shell Se nada for fornecido, o shell será o padrão presumido.
código	Lógica de negócios personalizada a ser executada como parte da tarefa personalizada.
inputProperties	Matriz de propriedades de entrada a serem capturadas como parte da configuração da tarefa personalizada. Essas propriedades normalmente são usadas no código.
outputProperties	Matriz de propriedades de saída que você pode exportar da tarefa personalizada para propagar ao pipeline.

Declare as propriedades de entrada no script usando os tipos de dados e metadados disponíveis.

As propriedades de entrada são transmitidas como contexto ao script na seção code: do YAML.


Chaves de entrada YAML da tarefa personalizada	Descrição	Obrigatório
`type`	Tipos de entrada para renderização: `text` `textarea` `number` `checkbox` `password` `select`	Sim
`name`	Nome ou cadeia de caracteres da entrada à tarefa personalizada, que é injetada no código YAML de integração personalizada. Deve ser exclusivo para cada propriedade de entrada definida para uma integração personalizada.	Sim
`title`	Rótulo da cadeia de caracteres de texto da propriedade de entrada à tarefa personalizada na tela do modelo de pipeline. Se deixado em branco, o `name` será usado por padrão.	Não
`required`	Determina se um usuário deve inserir a propriedade de entrada ao configurar a tarefa personalizada. Defina como verdadeiro ou falso. Quando verdadeiro, se um usuário não fornecer um valor ao configurar a tarefa customizada na tela do pipeline, o estado da tarefa permanecerá como não configurado.	Não
`placeHolder`	Texto padrão na área de entrada da propriedade de entrada quando nenhum valor está presente. Mapeia para o atributo do marcador de posição HTML. Compatível apenas com certos tipos de propriedades de entrada.	Não
`defaultValue`	Valor padrão que preenche a área de entrada da propriedade de entrada quando a tarefa personalizada é renderizada na página do modelo de pipeline.	Não
`bindable`	Determina se a propriedade de entrada aceita variáveis de cifrão ao modelar a tarefa personalizada na tela do pipeline. Adiciona o indicador $ ao lado do título. Compatível apenas com certos tipos de propriedades de entrada.	Não
`labelMessage`	Cadeia de caracteres que funciona como uma dica de ajuda aos usuários. Adiciona um ícone de dica de ferramenta i próximo ao título de entrada.	Não
`enum`	Recebe uma matriz de valores que exibe as opções para selecionar propriedades de entrada. Compatível apenas com certos tipos de propriedades de entrada. Quando um usuário seleciona uma opção e a salva para a tarefa personalizada, o valor de inputProperty corresponde a esse valor e aparece na modelagem da tarefa personalizada. Por exemplo, o valor 2015. 2015 2016 2017 2018 2019 2020	Não
`options`	Recebe uma matriz de objetos usando optionKey e optionValue. optionKey. Valor propagado para a seção de código da tarefa. optionValue. Cadeia de caracteres que exibe a opção na interface do usuário. Compatível apenas com certos tipos de propriedades de entrada. Options: optionKey: key1. Quando selecionado e salvo para a tarefa personalizada, o valor deste inputProperty corresponde a key1 na seção de código. optionValue: "Rótulo para 1". Exibe o valor de key1 na interface do usuário e não aparece em nenhum outro lugar da tarefa personalizada. optionKey: key2 optionValue: "Rótulo para 2" optionKey: key3 optionValue: "Rótulo para 3"	Não
`minimum`	Recebe um número que atua como o valor mínimo válido para essa propriedade de entrada. Compatível apenas com a propriedade de entrada do tipo de número.	Não
`maximum`	Recebe um número que atua como o valor máximo válido para essa propriedade de entrada. Compatível apenas com a propriedade de entrada do tipo de número.	Não

Tabela 3. Tipos de dados e metadados de dados compatíveis para scripts personalizados
Tipos de dados compatíveis	Metadados compatíveis para entrada
Cadeia de caracteres Texto Lista: como uma lista de qualquer tipo Mapa: como um mapa [string] qualquer Seguro: apresentado como uma caixa de texto de senha, criptografado quando você salva a tarefa personalizada Número Boolean: aparece como caixas de texto URL: igual à cadeia de caracteres, com validação adicional Botão de seleção, opção	tipo: uma da cadeia de caracteres \| Texto... padrão: valor padrão opções: lista ou um mapa de opções, a ser usado com botão de seleção ou opção mínimo: valor ou tamanho mínimo máximo: valor ou tamanho máximo título: nome detalhado da caixa de texto marcador de posição: marcador de posição da IU descrição: se torna uma dica de ferramenta

Por exemplo:

inputProperties:
        - name: message
          type: text
          title: Message
          placeHolder: Message for Slack Channel
          defaultValue: Hello Slack
          bindable: true
          labelInfo: true
          labelMessage: This message is posted to the Slack channel link provided in the code

Declare as propriedades de saída no script.

O script captura as propriedades de saída da seção de lógica de negócios code: do script, na qual você declara o contexto para a saída.

Quando o pipeline é executado, é possível inserir o código de resposta para a saída da tarefa. Por exemplo, 200.

Chaves que o Code Stream suporta para cada outputProperty.


chave	Descrição
type	Atualmente inclui um valor único de `label`.
name	Chave que o bloco de código do YAML de integração personalizada emite.
title	Rótulo na interface do usuário que exibe outputProperty.

Por exemplo:

outputProperties:
  - name: statusCode
    type: label
    title: Status Code

Para interagir com a entrada e saída do script personalizado, obtenha uma propriedade de entrada ou defina uma propriedade de saída usando context.

Para uma propriedade de entrada: (context.getInput("key"))

Para uma propriedade de saída: (context.setOutput("key", "value"))

Para Node.js:

var context = require("./context.js")
var message = context.getInput("message");
//Your Business logic
context.setOutput("statusCode", 200);

Para Python:

from context import getInput, setOutput
message = getInput('message')
//Your Business logic
setOutput('statusCode', '200')

Para Shell:

# Input, Output properties are environment variables
echo ${message} # Prints the input message
//Your Business logic
export statusCode=200 # Sets output property statusCode

Na seção code:, declare toda a lógica de negócios para sua integração personalizada.

Por exemplo, com o ambiente de tempo de execução Node.js:

code: |
    var https = require('https');
    var context = require("./context.js")
    
    //Get the entered message from task config page and assign it to message var
    var message = context.getInput("message");
    var slackPayload = JSON.stringify(
        {
            text: message
        });

    const options = {
        hostname: 'hooks.slack.com',
        port: 443,
        path: '/YOUR_SLACK_WEBHOOK_PATH',
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Content-Length': Buffer.byteLength(slackPayload)
        }
    };
    
    // Makes a https request and sets the output with statusCode which 
    // will be displayed in task result page after execution
    const req = https.request(options, (res) => {
        context.setOutput("statusCode", res.statusCode);
    });

    req.on('error', (e) => {
        console.error(e);
    });
    req.write(slackPayload);
    req.end();

Antes que você faça a versão e liberação de script de integração personalizado, faça o download do arquivo de contexto para Python ou Node.js e teste a lógica de negócios incluída no script.
1. Coloque o ponteiro do mouse na parte superior da tela e clique no botão do arquivo de contexto. Por exemplo, se o script estiver em Python, clique em CONTEXT.PY.
2. Modifique o arquivo e salve-o.
3. No sistema de desenvolvimento, execute e teste o script personalizado com a ajuda do arquivo de contexto.
Aplique uma versão ao script de integração personalizado.
1. Clique em Versão.
2. Insira as informações de versão.
3. Clique em Versão de Liberação para poder selecionar o script na tarefa personalizada.
4. Para criar a versão, clique em Criar.
(Opcional) Você pode definir qualquer versão lançada de um script de integração personalizado como a mais recente, para que ela apareça com o rótulo latest --> na tela do pipeline.
1. Coloque o ponteiro do mouse na parte superior da tela e clique em Histórico de Versões.
2. Para ver as ações disponíveis, clique nas reticências horizontais da versão desejada e selecione Definir como Mais Recente.
  
  Observação: Somente as versões lançadas aparecem com a ação Definir como Mais Recente.
3. Para confirmar a seleção da versão, clique em Definir como Mais Recente.
4. Para sair do Histórico de Versão e retornar à tela do editor de scripts, clique na seta para voltar.
Para salvar o script, clique em Salvar.
Para exportar o script como um arquivo YAML a ser usado em outra instância do Code Stream, clique em Ações > Exportar no cartão de integração personalizado e selecione as versões a serem exportadas.
No pipeline, configure o espaço de trabalho.
Neste exemplo, é usado um espaço de trabalho do Docker.
1. Clique na guia Espaço de Trabalho.
2. Selecione o host do Docker e o URL da imagem do compilador.
Adicione uma tarefa personalizada ao pipeline e configure-a.
1. Clique na guia Modelo.
2. Adicione uma tarefa, selecione o tipo como Personalizado e digite um nome relevante.
3. Selecione a versão e o script da integração personalizada. Se uma versão do script tiver sido definida como mais recente, ela será exibida com latest --> antes do nome da versão.
4. Para exibir uma mensagem personalizada no Slack, digite o texto da mensagem.
  Qualquer texto digitado substituirá o defaultValue no script de integração personalizado.
Salve e ative o pipeline.
1. Clique em Salvar.
2. No cartão de pipeline, clique em Ações > Ativar.
Execute o pipeline.
1. Clique em Executar.
2. Observe a execução do pipeline.
3. Confirme se a saída inclui o código de status esperado, o código de resposta, o status e a saída declarada.
  Você definiu statusCode como uma propriedade de saída. Por exemplo, um statusCode de 200 pode indicar uma publicação de Slack bem-sucedida e um responseCode de 0 pode indicar que o script foi bem-sucedido, sem erros.
4. Para confirmar a saída nos logs de execução, clique em Execuções, clique no link do pipeline, clique na tarefa e examine os dados registrados. Por exemplo:
Se ocorrer um erro, solucione o problema e execute o pipeline novamente.
Por exemplo, se um arquivo ou módulo na imagem de base estiver ausente, será necessário criar outra imagem de base que inclua o arquivo ausente. Em seguida, forneça o arquivo Docker e envie a imagem por meio do pipeline.

Resultados

Parabéns! Você criou um script de integração personalizado que conecta o Code Stream à instância de Slack e publica uma mensagem em um canal de Slack.

O que Fazer Depois

Continue a criar integrações personalizadas para oferecer suporte ao uso de tarefas personalizadas nos pipelines, para poder ampliar o recurso do Code Stream na automação do ciclo de liberação do software.