Crie fluxos de trabalho reutilizáveis no GitHub Actions
Fluxos de trabalho reutilizáveis permitem que você adote o princípio DRY (Don't Repeat Yourself, não se repita), introduza padronização e implemente práticas recomendadas de maneira consistente. Eles facilitam as jornadas dos desenvolvedores, tornando os processos mais simplificados e eficientes, sem impor restrições indevidas. À medida que avançarmos, a Deutsche Vermögensberatung AG (DVAG) se juntará a nós para seus conselhos sobre como tirar o máximo proveito dos fluxos de trabalho reutilizáveis.
Neste guia, você aprenderá:
Os usos e benefícios dos fluxos de trabalho reutilizáveis
Os componentes essenciais e a sintaxe necessária para criar fluxos de trabalho reutilizáveis
A estrutura e a sintaxe do URL para invocar um fluxo de trabalho reutilizável (reusable workflow)
Como incorporar fluxo de trabalho reutilizável (reusable workflow) em projetos armazenados em repositórios separados
O que são fluxos de trabalho reutilizáveis (reusable workflows) e como funcionam?
Um fluxo de trabalho reutilizável (reusable workflow) é um arquivo do GitHub Actions que pode ser executado por outros fluxos de trabalho. Um único fluxo de trabalho pode chamar vários fluxos de trabalho reutilizáveis (reusable workflows), com cada referência ocupando apenas uma linha de YAML. Isso significa que o fluxo de trabalho “chamador” pode conter apenas algumas linhas de YAML, mas executar um grande número de tarefas, pois executa cada fluxo de trabalho “chamado” inteiramente, como se seus trabalhos e etapas fizessem parte dele. Além disso, os fluxos de trabalho podem ser aninhados em até quatro níveis.
Quais são os benefícios dos fluxos de trabalho reutilizáveis (reusable workflows)?
Os fluxos de trabalho reutilizáveis (reusable workflows) oferecem vários benefícios:
Evitam redundância
Aceleram a criação de fluxo de trabalho por meio da reutilização
Reduzem a manutenção e melhoram a segurança oferecendo uma biblioteca de fluxos de trabalho reutilizáveis que podem ser mantidos centralmente
Promovem o uso de fluxos de trabalho bem projetados, já testados e comprovadamente eficazes
Com esses benefícios em mente, e em combinação com grupos de executores (runner groups), as organizações podem criar caminhos pavimentados para os desenvolvedores que lhes permitam dedicar tempo ao trabalho em questão, em vez de gerenciar a infraestrutura ou recriar fluxos de trabalho existentes.
Centralizamos nossos fluxos de trabalho em um monorepo onde todas as alterações exigem a aprovação do proprietário do código para garantir uniformidade e qualidade ao longo do tempo, ao mesmo tempo em que possibilitamos propriedade especializada para determinados fluxos de trabalho. Usamos controle de versão semântico e evitamos mudanças drásticas ao seguir um esquema de versão 1.x.x. Geralmente lançamos novas versões de fluxo de trabalho semanalmente, usando a funcionalidade auto-merge para manter as atualizações fluindo e testando-as tanto no main branch quanto nos repositórios de teste. Também monitoramos ativamente o uso do fluxo de trabalho em todos os repositórios, para que possamos garantir que eles estejam sendo usados de forma eficaz.
Componentes de um fluxo de trabalho reutilizável (reusable workflow)
O evento acionador
Para que um fluxo de trabalho seja reutilizável, os valores de on devem incluir workflow_call:
on:
workflow_call:
Definição de entrada
É possível definir entradas e segredos em um fluxo de trabalho reutilizável (reusable workflow) para recebê-los de um fluxo de trabalho do chamador. Use as palavras-chave inputs e secrets para este propósito. Para obter mais informações, consulte nosso guia sobre como proteger CI/CD com segredos e variáveis. Veja abaixo uma versão comentada de um exemplo de fluxo de trabalho reutilizável (reusable workflow):
on: # Specifies the event triggering the workflow
workflow_call: # Indicates that this is a reusable workflow
inputs: # Defines the inputs that can be passed from the caller workflow
config-path: # Name of the input
required: true # Specifies that this input is mandatory
type: string # Specifies the type of the input
secrets: # Defines the secrets that can be passed from the caller workflow
envPAT: # Name of the secret
required: true # Specifies that this secret is mandatory
No exemplo acima, envPAT é um segredo de ambiente que foi adicionado ao ambiente de produção. Portanto, esse ambiente é referenciado dentro do trabalho.
Passagem de segredos nomeados
Para passar entradas nomeadas para um fluxo de trabalho chamado, use a palavra-chave with em um trabalho. Use a palavra-chave secrets para passar segredos nomeados. Para entradas, o tipo de dados do valor de entrada deve corresponder ao tipo especificado no fluxo de trabalho chamado (booleano, número ou string).
jobs:
call-workflow-passing-data:
uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
with:
config-path: .github/labeler.yml
secrets:
envPAT: ${{ secrets.envPAT }}
Os fluxos de trabalho que chamam fluxos de trabalho reutilizáveis (reusable workflows) na mesma organização ou empresa podem usar a palavra-chave inherit para transmitir implicitamente os segredos.
jobs:
call-workflow-passing-data:
uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
with:
config-path: .github/labeler.yml
secrets: inherit
Dependemos do Dependabot para distribuir automaticamente atualizações de nossos fluxos de trabalho reutilizáveis para equipes e projetos. Cada versão aciona de forma automática uma pull request nos repositórios do usuário, que acompanhamos rigorosamente em um problema dedicado. Assim sabemos quem atualizou ou não seus fluxos de trabalho e temos uma forma otimizada de garantir que todo mundo esteja informado, usando os fluxos de trabalho mais atuais e efetivos.
Chamar GitHub Actions reutilizáveis
Você chama um fluxo de trabalho reutilizável (reusable workflow) usando a palavra-chave uses . Ao contrário de quando você usa o GitHub Actions em um fluxo de trabalho, você chama fluxos de trabalho reutilizáveis (reusable workflows) diretamente em um trabalho e não nas etapas do trabalho. Vamos analisar a estrutura da URL para chamar um fluxo de trabalho reutilizável (reusable workflow). No exemplo acima, você verá a linha:
uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
Podemos ver que o código segue uma estrutura específica:
uses: [OWNER/REPOSITORY PATH]/[.github/workflows/WORKFLOW_FILE]@[REF]
Cada segmento desta estrutura tem uma finalidade específica:
1. uses:
Esta é uma palavra-chave na sintaxe do GitHub Actions que indica que a sequência a seguir fará referência a um trecho de código reutilizável, como uma Action ou, neste caso, um fluxo de trabalho reutilizável (reusable workflow).
2. OWNER:
Isso especifica o usuário ou organização do GitHub que possui o repositório onde o fluxo de trabalho reutilizável (reusable workflow) está localizado (ex: octo-org).
3. REPOSITORY PATH:
Este é o caminho para o repositório (ex: example-repo/).
4. .github/workflows/:
Este é um caminho convencional onde o Actions espera encontrar definições de fluxo de trabalho em um repositório. Todos os arquivos YAML do fluxo de trabalho devem estar localizados neste diretório para que sejam reconhecidos e executados pelo Actions.
5. WORKFLOW_FILE:
Isso especifica o arquivo YAML exato que contém a definição do fluxo de trabalho. (ex: reusable-workflow.yml).
6. @REF:
Isso indica o branch, tag ou commit SHA a partir do qual o fluxo de trabalho deve ser usado. É essencial especificar isso para que o Actions saiba qual versão do fluxo de trabalho usar. Isso será particularmente útil se os fluxos de trabalho evoluírem ao longo do tempo e você desejar garantir que uma versão específica seja usada em seu próprio fluxo de trabalho (ex: @main).
Como tornar um fluxo de trabalho reutilizável
Veja aqui um exemplo do fluxo de trabalho build-test-deploy.yml que criamos no módulo Fundamentos de automação. Abaixo, atualizamos o arquivo para aceitar a reutilização. Além de adicionar workflow_call, também definimos parâmetros que nos permitem configurar o node-version. Preste atenção aos comentários descritos no código:
name: build-test-deploy
# Changed 'on' to enable this workflow to be called from other workflows
on:
workflow_call:
# Introduced 'inputs' to define parameters that can be passed when calling this workflow
inputs:
node-version:
description: "Node version"
required: true
type: string
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: checkout repo
uses: actions/checkout@v3
# Modified to use the node-version from the workflow inputs
- name: use node.js
uses: actions/setup-node@v3
with:
node-version: ${{ inputs.node-version }}
- run: npm install
- run: npm run build
test:
needs: build
runs-on: ubuntu-latest
steps:
- name: checkout repo
uses: actions/checkout@v3
# Modified to use the node-version from the workflow inputs
- name: use node.js
uses: actions/setup-node@v3
with:
node-version: ${{ inputs.node-version }}
- run: npm install
- run: npm run testAgora que atualizamos o nosso fluxo de trabalho build-test-deploy para aceitar a reutilização e entendemos como chamar um fluxo de trabalho reutilizável, vamos juntar tudo. No código de exemplo abaixo, chamamos o fluxo de trabalho build-test-deploy de um fluxo de trabalho localizado em um repositório separado:
jobs:
my-job:
# Importing a reusable workflow from another repository and branch
uses: organization/repo/.github/workflows/build-test-deploy.yml@main
# Passing 'node-version' as an input parameter to the reusable workflow
with:
node-version: '18.x'
A seguir: Gerencie e monitore fluxos de trabalho no GitHub Actions
Pronto para otimizar a forma como você gerencia e monitora seus GitHub Actions? Confira nosso guia detalhado. Da análise do status do fluxo de trabalho ao monitoramento do uso de recursos, equiparemos você com as ferramentas necessárias para operar com mais eficiência.