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

  1. Crie a integração personalizada.
    1. Clique em Integrações Personalizadas > Novo e insira um nome relevante.
    2. Selecione o ambiente de tempo de execução preferencial.
    3. 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.
  2. 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
    
  3. 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
  4. 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
    
  5. 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();
    
  6. 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.
  7. 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.
      Você cria uma versão do seu script de integração personalizado e seleciona a versão na tarefa Personalizada do seu pipeline.
  8. (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.
      Depois de criar uma versão e lançar um script de integração personalizado, você poderá definir a versão como mais recente para que um usuário saiba qual versão atual deve ser selecionada no pipeline.
    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.
  9. 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.
  10. 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.
      Ao criar uma integração customizada, você inclui o host, a URL da imagem do construtor e o registro da imagem.
  11. 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.
      Ao adicionar uma tarefa personalizada ao seu pipeline, você seleciona uma versão do seu script personalizado.
  12. Salve e ative o pipeline.
    1. Clique em Salvar.
    2. No cartão de pipeline, clique em Ações > Ativar.
  13. 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:
      Depois que o pipeline executar sua tarefa personalizada, você poderá visualizar a saída da tarefa para a integração personalizada nas execuções do pipeline.
  14. 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.