Criar sua primeira ação personalizada do GitHub

Por último neste módulo, discutiremos a justificativa para a criação de uma ação personalizada do GitHub e orientaremos você durante sua criação.

Começaremos descrevendo a configuração do seu action.yml e index.js- o modelo de configuração e a lógica de ação, respectivamente para uma ação "Hello World" básica. Além disso, abordaremos as melhores práticas para liberar sua ação no GitHub Marketplace, incluindo versionamento semântico, e o Datadog oferecerá alguns insights sobre a importância de ouvir seus clientes durante o processo. Juntas, essas etapas oferecem uma abordagem simplificada para automatizar fluxos de trabalho de projetos GitHub.

Neste guia, você aprenderá como:

• Decidir quando criar uma ação personalizada

• Escrever um arquivo actions.yml simples, mas eficaz, que descreva os metadados de suas ações, incluindo entradas e saídas

• Conectar sua ação à lógica de tempo de execução usando partes específicas do código JavaScript para fazer fetch de entradas e definir saídas

• Executar as melhores práticas para publicar sua ação no GitHub Marketplace elaborando uma versão e adotando o versionamento semântico

Decidir quando criar uma ação personalizada

Antes de mergulhar no desenvolvimento de uma ação personalizada, avalie a escolha entre usar ações existentes no GitHub Marketplace ou criar uma ação personalizada. Esta decisão afeta não apenas a eficiência do seu desenvolvimento, mas também a governança e a postura de segurança da sua empresa.

Governança: controlar suas ações

Quanto controle você precisa ou deseja ter sobre as ações que sua organização utiliza? O GitHub permite que você defina políticas específicas para uso de ações em sua organização. Navegar até a seção "Actions General" nas configurações da sua organização permite restringir o uso a ações criadas pelo GitHub ou por criadores verificados, que passaram por um processo de verificação e geralmente são consideradas seguras.

As ações do marketplace, especialmente de criadores verificados, oferecem uma vantagem importante: são avaliadas por alguns dos principais profissionais de segurança do setor. Se a governança e o controle absoluto sobre o código forem fundamentais, as ações personalizadas desenvolvidas internamente poderão ser o caminho a seguir. É possível armazená-los em uma pasta "Actions" dentro dos repositórios da sua organização, tornando mais fácil gerenciá-los e auditá-los.

Facilidade de uso versus personalização

As ações do marketplace são soluções convenientes e prontas para usar para tarefas comuns, mas nem sempre podem estar perfeitamente alinhadas com as necessidades da sua empresa. As ações personalizadas, por outro lado, oferecem a flexibilidade de adaptar o código executável para atender aos seus requisitos específicos e podem ser reutilizadas em vários projetos da sua empresa, uma vez desenvolvidos e avaliados quanto a questões de segurança. Usar o innersourcing em suas ações em toda a empresa é uma excelente maneira de acelerar a inovação e, ao mesmo tempo, reduzir os riscos. 

Se você achar que as ações do Marketplace estão consistentemente próximas, mas não totalmente corretas, há também a opção intermediária de criar fork ou clonar essas ações e depois modificá-las. Isso fornece a conveniência de ações pré-criadas juntamente com a personalização de ações personalizadas.

Criar uma ação não é um processo simples e rápido. Com qualquer software, precisa passar por manutenção. Priorize suas iniciativas baseadas em plataformas e sistemas que seus clientes já estão usando. Não criamos nossa ação personalizada do GitHub como Datadog apenas para praticar. Nossos clientes queriam uma ferramenta que pudesse ser integrada perfeitamente aos seus pipelines de integração contínua existentes, muitos dos quais já existentes no GitHub. Nossa ação foi criada para atender a uma necessidade real de clientes.

Jake Pruitt // Senior Engineer // Datadog

Mesmo que você não crie ações personalizadas, entender o processo é útil, então vamos em frente.

Escrever o arquivo action.yml

Para começar, crie um novo arquivo chamado action.yml no seu repositório.

1. Defina seu nome e uma descrição.

Comece especificando um name e description. Isso é o que os usuários, inclusive você, verão ao navegar pelas ações internas da sua empresa ou pelo Marketplace.

name: 'Hello World JS Action'
description: 'Greet someone and record the time'

2. Declare as entradas.

Declare as entradas da ação. Esses parâmetros os seus fluxos de trabalho poderão passar para a ação ao utilizá-la. Em nosso exemplo, a entrada é who-to-greet.

inputs:
  who-to-greet:
    description: 'Who to greet'
    required: true
    default: 'World'

3. Descrever os resultados.

Descreva o resultado da ação. Isso pode ser usado em etapas subsequentes do mesmo trabalho. Para nossa ação simples, o resultado é o horário da saudação.

outputs:
  time:
    description: 'The time we greeted you'

4. Defina o ambiente de execução.

Por fim, especifique o ambiente de execução e aponte para o arquivo JavaScript que contém a lógica da sua ação.

runs:
  using: 'node16'
  main: 'index.js'

É isso! Você preparou o cenário para que seu código JavaScript dê vida a essa ação.

Criando a lógica

Assim que o arquivo action.yml estiver pronto, o próximo componente é o arquivo JavaScript, que no nosso caso é index.js. É aqui que você incorporará a lógica operacional da ação. Para conectar o seu código JavaScript à ação, você usará as próprias bibliotecas do GitHub, especificamente, @actions/core e @actions/github.

const core = require('@actions/core');
const github = require('@actions/github');



try {
  // Fetch the value of the input 'who-to-greet' specified in action.yml
  const nameToGreet = core.getInput('who-to-greet');
  console.log(`Hello ${nameToGreet}!`);
  
  // Record the time of greeting as an output
  const time = (new Date()).toTimeString();
  core.setOutput("time", time);



} catch (error) {
  // Handle errors and indicate failure
  core.setFailed(error.message);
}

Veja aqui um detalhamento simplificado do código JavaScript, destacando as partes essenciais para sua ação:

1. core.getInput('who-to-greet'): isso fará fetch do valor que você definiu como entrada em action.yml, e saudamos essa entidade na ação.

2. core.setOutput("time", time): isso definirá a saída, especificamente a hora em que você fez a saudação, que pode ser usada nas etapas subsequentes do fluxo de trabalho.

3. try/catch block: garante o fácil tratamento de quaisquer exceções, sinalizando uma falha com core.setFailed(error.message) se necessário.

É isso! Com esses elementos em seu index.js, a sua ação está funcional e pronta para automação de nível empresarial.

Liberar sua ação

Depois de adicionar os arquivos necessários ao seu repositório GitHub, um novo prompt aparecerá na parte superior da página de código do seu repositório, informando “Publicar esta ação no GitHub Marketplace”. Clicar aqui o direcionará para a página “Elaborar um novo lançamento” personalizada para o Actions.

Ao liberar ações no Marketplace, lembre-se:

• Versionamento semântico: utilize o versionamento semântico para a versão da sua tag. Isso ajuda a simplificar o controle de versão e é altamente recomendado para ações.

• Descrição e categorias: certifique-se de fornecer uma descrição clara do que a ação faz e selecione a categoria que melhor descreve a utilidade da sua ação, seja Integração Contínua, IA, Chat ou qualquer outra coisa.

• Publicar: depois de validar os detalhes, vá em frente e clique em Publish release. Sua ação estará disponível no Marketplace, marcada com a versão semântica que você especificou.

Parabéns! Você entrou no Marketplace!

A seguir: Estratégia de automação avançada com conclusão do módulo GitHub Actions

Agora vamos revisar o que aprendemos até agora e dar uma olhada no que mais podemos fazer com GitHub Actions.