Criar uma ação personalizada do GitHub

Concluído

O GitHub Actions é um recurso avançado que ajuda você a ir do código à nuvem, tudo isso no conforto e na conveniência de seu repositório. Aqui você aprenderá sobre os diferentes tipos de ações do GitHub e os metadados, a sintaxe e os comandos de fluxo de trabalho para criar ações personalizadas do GitHub.

Tipos de ações do GitHub

As ações são tarefas individuais que você pode usar para personalizar seus fluxos de trabalho de desenvolvimento. Você pode criar suas ações escrevendo código personalizado que interage com seu repositório para executar tarefas personalizadas ou usando ações compartilhadas pela comunidade do GitHub. Navegando por várias ações, você observará que há três tipos diferentes delas: ações de contêiner do Docker, ações de JavaScript e ações de etapas de execução compostas. Vamos examinar cada tipo de ação em mais detalhes.

Ações de contêiner do Docker

Os contêineres do Docker empacotam o ambiente com o código do GitHub Actions. Isso significa que a ação é executada em um ambiente consistente e confiável porque todas as suas dependências estão dentro desse contêiner. Se a ação precisar ser executada em uma configuração de ambiente específica, os contêineres do Docker serão uma boa opção, pois você pode personalizar o sistema operacional e as ferramentas. A desvantagem é que, como o trabalho precisa criar e recuperar o contêiner, as ações de contêiner do Docker geralmente são mais lentas do que as ações de JavaScript.

Antes de criar uma ação de contêiner do Docker, você deve ter um entendimento básico de como usar as variáveis de ambiente e o sistema de arquivos de contêiner do Docker. As etapas para criar uma ação de contêiner do Docker são mínimas e diretas:

1. Crie um Dockerfile para definir os comandos a fim de montar a imagem do Docker.
2. Crie um arquivo de metadados action.yml para definir as entradas e saídas da ação. Defina o valor runs: using: como docker e o valor runs: image: como Dockerfile no arquivo.
3. Crie um arquivo entrypoint.sh para descrever a imagem do Docker.
4. Confirme e efetue push da sua ação para o GitHub com os seguintes arquivos: action.yml, entrypoint.shDockerfile e README.md.

Ações de JavaScript

As ações de JavaScript podem ser executadas diretamente no computador executor e separar o código de ação do ambiente usado para executar a ação. Por isso, o código de ação é simplificado e pode ser executado mais rápido do que as ações em um contêiner do Docker.

Como pré-requisito para criar e usar ações de JavaScript empacotadas, você precisa baixar o Node.js, que inclui NPM. Como uma etapa opcional, mas recomendada, é usar o Kit de ferramentas do GitHub Actions Node.js, que é uma coleção de pacotes Node.js que permite a criação rápida de ações de JavaScript com mais consistência.

As etapas para criar uma ação de JavaScript são mínimas e diretas:

1. Crie um arquivo de metadados action.yml para definir as entradas e saídas da ação, além de informar ao executor da ação como começar a executar essa ação de JavaScript.
2. Crie um arquivo index.js com informações de contexto sobre os pacotes do kit de ferramentas, o roteamento e outras funções da ação.
3. Confirme e efetue push da sua ação para o GitHub com os seguintes arquivos: action.yml, index.jsnode_modules, package.json, package-lock.json e README.md.

Ações de etapas de execução compostas

As ações de etapas de execução compostas permitem reutilizar ações usando scripts de shell. Você pode até mesmo misturar várias linguagens de shell dentro da mesma ação. Se você tiver muitos scripts de shell para automatizar diversas tarefas, poderá transformá-los facilmente em uma ação e reutilizá-los em diferentes fluxos de trabalho. Às vezes, é mais fácil apenas escrever um script de shell do que usar o JavaScript ou encapsular seu código em um contêiner do Docker.

Metadados e sintaxe necessários para criar uma ação

Ao criar ou revisar uma ação do GitHub, uma ótima primeira etapa é examinar o arquivo action.yml para avaliar as entradas, saídas, descrição, execuções e outras informações de configuração são necessárias para a ação. Alguns dos parâmetros são necessários, enquanto outros são opcionais. O arquivo action.yml define as seguintes informações sobre sua ação:

Parâmetro	Descrição	Obrigatório
Nome	O nome da sua ação. Ajuda a identificar visualmente a ação em um trabalho.	sim
Descrição	Um resumo do que a ação faz.	sim
Entradas	Os parâmetros de entrada permitem que você especifique os dados que a ação pretende usar durante o tempo de execução. Esses parâmetros se tornam variáveis de ambiente no executor.	não
Saídas	Os parâmetros de saída permitem que você especifique os dados que as ações subsequentes poderão usar posteriormente no fluxo de trabalho depois que a ação que define essas saídas tiver sido executada.	não
Execuções	O comando a ser executado quando a ação é executada.	sim
Identidade visual	Ícone de cor e do Feather a ser usado para criar uma notificação a fim de personalizar e distinguir sua ação no Marketplace do GitHub.	não

Entradas

As entradas são os parâmetros que permitem que você especifique os dados que a ação pretende usar durante o tempo de execução. O GitHub armazena esses parâmetros de entrada como variáveis de ambiente.

A seguir, temos um exemplo de lista de entradas para uma ação. A entrada firstNameStudent é opcional, e a entrada studentGrade é obrigatória.

inputs:
  firstNameStudent:
    description: 'First name of student'
    required: false
    default: '1'
  studentGrade:
    description: 'Grade of the student'
    required: true

Saídas

Saídas são os parâmetros que permitem que você declare dados. Tenha em mente que as ações que são executadas posteriormente em um fluxo de trabalho poderão usar os dados de saída que foram declarados em uma ação executada anteriormente.

Este exemplo é uma saída simples para declarar a nota média dos alunos:

outputs:
  average:
    description: 'The average grade of the students'

Execuções

Como você aprendeu anteriormente, sua ação precisa ter uma instrução runs que define o comando necessário para executar a ação. Dependendo de como você estiver criando a ação – se está usando um contêiner do Docker, JavaScript ou etapas de execução compostas –, a sintaxe runs será definida de maneira diferente.

runs para ações do Docker

As ações do contêiner do Docker exigem a instrução runs para configurar a imagem usada para a ação do Docker com os seguintes argumentos:

• using: precisa ser definido como docker para executar uma ação de contêiner do Docker.
• image: imagem do Docker usada como contêiner para executar a ação.

runs:
  using: 'docker'
  image: 'Dockerfile'

runs para ações de JavaScript

As ações de JavaScript exigem que a instrução runs use os seguintes dois argumentos:

• using: aplicativo usado para executar o código conforme definido em main.
• main: arquivo que contém o código de ação; o aplicativo definido em using executa esse arquivo.

Por exemplo, aqui está uma instrução runs para uma ação JavaScript que usa o Node.js:

runs:
  using: 'node12'
  main: 'main.js'

runs para ações de etapas de execução compostas

As ações de etapas de execução compostas exigem que a instrução runs execute os três seguintes argumentos:

• using: precisa ser definido como "composite" para executar uma etapa de execução composta.
• steps: execute as etapas para executar a ação.
• steps[*].run: comando que você deseja executar (pode ser embutido ou um script no repositório de ações).

Por exemplo, aqui está uma instrução runs para uma ação de etapas de execução compostas que executará o script no filepath /test/script/sh:

runs:
  using: "composite"
  steps:
    - run: ${{ github.action_path }}/test/script.sh
      shell: bash

Identidade visual

Um recurso opcional, mas divertido, é a capacidade de personalizar o selo de sua ação. O selo é exibido ao lado do nome da ação no Marketplace do GitHub. Você pode usar um ícone de cor e do Feather para criar o selo. No caso da identidade visual, você precisará especificar o ícone e a cor que deseja usar.

branding:
  icon: 'shield'  
  color: 'blue'

Aqui está um exemplo de um selo de ação de Finalizar compra no Marketplace do GitHub:

Comandos de fluxo de trabalho

A criação de um fluxo de trabalho é bem simples, desde que você possa encontrar as ações certas para suas etapas. Em alguns casos, talvez seja necessário criar suas ações para atingir os resultados desejados, mas você pode usar comandos de fluxo de trabalho para adicionar outro nível de personalização aos fluxos de trabalho.

Os comandos de fluxo de trabalho permitem que você se comunique com o computador executor do GitHub Actions imprimindo linhas de texto formatadas no console. Use esses comandos de fluxo de trabalho com comandos shell ou em suas ações personalizadas. Os comandos de fluxo de trabalho são úteis porque permitem compartilhar informações entre etapas do fluxo de trabalho, imprimir mensagens de erro ou depuração no console, definir variáveis de ambiente, definir parâmetros de saída ou adicionar ao caminho do sistema.

A maioria dos comandos de fluxo de trabalho usa o comando echo no formato específico abaixo, enquanto outros podem ser invocados por meio da gravação em um arquivo:

echo "::workflow-command parameter1={data},parameter2={data}::{command value}"

Veja abaixo alguns exemplos básicos de registro de mensagens em log para imprimir uma mensagem de depuração, de informações, de erro ou de aviso no console:

- name: workflow commands logging messages
  run: |
    echo "::debug::This is a debug message"
    echo "This is an info message"
    echo "::error::This is an error message"
    echo "::warning::This is a warning message"

Você também pode criar uma mensagem para imprimir no log com um nome de arquivo (file), número de linha (line) e número de coluna (col) em que o erro ocorreu. As mensagens de aviso aparecem em realce amarelo com o texto "aviso" e as mensagens de erro aparecem em realce vermelho com o texto "erro".

echo "::error file=app.js,line=10,col=15::Something went wrong"

É importante observar que esses comandos de fluxo de trabalho precisam estar em uma mesma linha. Caracteres que interferem na análise, como vírgulas e quebras de linha, precisarão ser codificados por URL.

Por exemplo, o seguinte texto é uma mensagem de várias linhas:

This text spans
across multiple lines

Esta mensagem deve ser codificada conforme mostrado aqui:

This text spans%0Aacross multiple lines

Além dos comandos de fluxo de trabalho, você pode definir códigos de saída para definir o status de uma ação. Isso é importante porque, quando você estiver mexendo em trabalhos em um fluxo de trabalho, um código de saída com falha interromperá todas as ações simultâneas e cancelará as ações futuras. Se você está criando uma ação de JavaScript, pode usar o pacote do kit de ferramentas de ações @actions/core para registrar uma mensagem e definir um código de saída de falha. Se você está criando uma ação de contêiner do Docker, pode definir um código de saída de falha em seu script entrypoint.sh.