Criar uma ação personalizada do GitHub

Concluído

O GitHub Actions é um recurso poderoso que ajuda você a ir do código para a nuvem, tudo a partir do conforto e conveniência do seu próprio repositório. Aqui, você aprenderá sobre os diferentes tipos de ações do GitHub e os metadados, sintaxe e 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 próprias ações escrevendo código personalizado que interage com seu repositório para executar tarefas personalizadas ou usando ações compartilhadas pela comunidade GitHub. Navegando por várias ações, você notará que há três tipos diferentes de ações: ações de contêiner do Docker, ações JavaScript e ações de etapas de execução compostas. Vamos dar uma olhada mais de perto em cada tipo de ação.

Ações do contêiner do Docker

Os contêineres do Docker empacotam o ambiente com o código 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 são um bom caminho a seguir, 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 do contêiner do Docker geralmente são mais lentas do que as ações JavaScript.

Antes de criar uma ação de contêiner do Docker, você deve ter alguma compreensão básica de como usar variáveis de ambiente e o sistema de arquivos de contêiner do Docker. As etapas a serem executadas para criar uma ação de contêiner do Docker são, então, mínimas e diretas:

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

Ações JavaScript

As ações JavaScript podem ser executadas diretamente na máquina runner 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 rapidamente do que as ações dentro de um contêiner do Docker.

Como pré-requisito para criar e usar ações JavaScript empacotadas, você precisa fazer o download Node.js, que inclui npm. Como uma etapa opcional (mas que recomendamos) é usar o GitHub Actions Toolkit Node.js, que é uma coleção de pacotes de Node.js que permite criar rapidamente ações JavaScript com mais consistência.

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

1. Crie um action.yml arquivo de metadados para definir as entradas e saídas da ação, bem como diga ao executor de ação como começar a executar essa ação JavaScript.
2. Crie um index.js arquivo com informações de contexto sobre os pacotes do Toolkit, roteamento e outras funções da ação.
3. Confirme e envie sua ação para o GitHub com os seguintes arquivos: action.yml, index.js, node_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 shell scripts. Você pode até mesmo misturar vários idiomas de shell dentro da mesma ação. Se você tiver muitos shell scripts para automatizar várias tarefas, agora poderá transformá-los facilmente em uma ação e reutilizá-los para fluxos de trabalho diferentes. Às vezes, é mais fácil apenas escrever um shell script do que usar 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, um ótimo primeiro passo é revisar o action.yml arquivo para avaliar quais entradas, saídas, descrição, execuções e outras informações de configuração a ação precisa. Alguns desses parâmetros são necessários, enquanto outros são opcionais. O action.yml arquivo 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
Description	Um resumo do que a sua ação faz.	sim
Entradas	Os parâmetros de entrada permitem especificar os dados que a ação espera usar durante o tempo de execução. Estes parâmetros tornam-se variáveis de ambiente no corredor.	não
Saídas	Os parâmetros de saída permitem especificar dados que as ações subsequentes podem usar posteriormente no fluxo de trabalho após a execução da ação que define essas saídas.	não
Execuções	O comando a ser executado quando a ação é executada.	sim
Imagem corporativa	Ícone de cor e pena para usar para criar um selo para personalizar e distinguir sua ação no GitHub Marketplace.	não

Entradas

Entradas são os parâmetros que permitem especificar dados que a ação espera usar durante seu tempo de execução. O GitHub armazena esses parâmetros de entrada como variáveis de ambiente.

Segue-se um exemplo de uma lista de entradas para uma ação. A firstNameStudent entrada é opcional, enquanto a studentGrade entrada é necessária.

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

Saídas

As saídas são os parâmetros que permitem declarar dados. Lembre-se de que as ações executadas posteriormente em um fluxo de trabalho podem usar os dados de saída declarados em uma ação executada anteriormente.

O exemplo a seguir é 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 runs instrução que defina o comando necessário para executar sua ação. Dependendo de como você está criando sua ação, se você está usando um contêiner do Docker, JavaScript ou etapas de execução compostas, a runs sintaxe é definida de forma diferente.

runs para ações do Docker

As ações de contêiner do Docker exigem que a runs instrução configure a imagem que a ação do Docker usa com os seguintes argumentos:

• using: Precisa ser definido para docker 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 JavaScript

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

• using: Aplicação utilizada para executar o código conforme definido em main
• main: Arquivo que contém o código da ação; O aplicativo definido em using executa este arquivo

Por exemplo, aqui está uma runs instrução para uma ação JavaScript usando 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 runs instrução use os três argumentos a seguir:

• using: Precisa ser definido para "composite" executar uma etapa de execução composta
• steps: Execute etapas para executar a ação
• steps[*].run: Comando que você deseja executar (pode ser embutido ou um script em seu repositório de ações)

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

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

Imagem corporativa

Um recurso opcional, mas divertido, é a capacidade de personalizar o emblema da sua ação. O selo é exibido ao lado do nome da ação no GitHub Marketplace. Você pode usar um ícone de cor e pena para criar o selo. Para a marca, 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 checkout no GitHub Marketplace:

Comandos de fluxo de trabalho

Criar um fluxo de trabalho é bastante simples, desde que você possa encontrar as ações certas para suas etapas. Em alguns casos, talvez seja necessário criar suas próprias ações para alcançar 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 a máquina executora de ações do GitHub imprimindo linhas formatadas de texto no console. Você pode usar esses comandos de fluxo de trabalho com comandos shell ou dentro de suas ações personalizadas. Os comandos de fluxo de trabalho são úteis porque permitem compartilhar informações entre as etapas do fluxo de trabalho, imprimir mensagens de depuração ou erro 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 echo comando no seguinte formato específico, enquanto outros podem ser invocados gravando em um arquivo:

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

A seguir estão alguns exemplos básicos de registro de mensagens para imprimir uma mensagem de depuração, mensagem de informações, mensagem de erro ou mensagem de aviso para o 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 (arquivo), número de linha (linha) e número de coluna (col) onde o erro ocorreu. As mensagens de aviso aparecem em um realce amarelo com o texto "aviso" e as mensagens de erro aparecem em um 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 única linha. Os caracteres que interferem na análise, como vírgulas e quebras de linha, precisarão ser codificados por URL.

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

This text spans
across multiple lines

Esta mensagem deve ser codificada como 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ê está trabalhando com trabalhos em um fluxo de trabalho, um código de saída com falha interromperá todas as ações simultâneas e cancelará quaisquer ações futuras. Se você estiver criando uma ação JavaScript, poderá 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ê estiver criando uma ação de contêiner do Docker, poderá definir um código de saída de falha em seu entrypoint.sh script.