Gerenciando e aproveitando componentes reutilizáveis no GitHub Actions

  • 9 minutos

Na unidade anterior, você explorou como estruturar políticas e modelos do GitHub Actions nos níveis corporativo e organizacional. Nesta unidade, você se aprofundará em como gerenciar e manter componentes reutilizáveis, como fluxos de trabalho, ações personalizadas e scripts de automação, em vários repositórios.

Gerenciando e aproveitando componentes reutilizáveis no GitHub Actions

Componentes reutilizáveis no GitHub Actions referem-se a fluxos de trabalho, ações e scripts que são usados em vários repositórios para simplificar o desenvolvimento e a automação. Eles ajudam a padronizar pipelines de CI/CD, melhorar a manutenção e reduzir os esforços de configuração redundantes.

Tipos de componentes reutilizáveis

  1. Fluxos de trabalho reutilizáveis
    • Definido uma vez e referenciado em vários repositórios.
    • Exemplo: um fluxo de trabalho de build e implantação padrão para todos os projetos em uma empresa.
  2. Ações personalizadas do GitHub
    • Criado para tarefas repetidas (por exemplo, configurando dependências, executando verificações de segurança).
    • Exemplo: Uma ação em toda a empresa para impor o linting de código.
  3. Scripts Compartilhados
    • Scripts Bash, PowerShell ou Python usados em fluxos de trabalho para automatizar tarefas.
    • Exemplo: um script para gerar relatórios de conformidade para repositórios de código.

Criando repositórios centralizados para componentes reutilizáveis

Um repositório bem estruturado para fluxos de trabalho e ações reutilizáveis garante fácil acesso e padronização. Considere a criação do seguinte:

Tipo do repositório Finalidade Convenção de nomenclatura de exemplo
Repositório de Ações Armazena ações personalizadas do GitHub usadas em projetos. org-actions-repo
Repositório de fluxos de trabalho Contém fluxos de trabalho reutilizáveis para automação de CI/CD. org-reusable-workflows
Repositório de scripts Mantém scripts reutilizáveis para automação. org-scripts-library

Estrutura de exemplo para um repositório de ações:

org-actions-repo/
│── setup-node/         # Custom GitHub Action for Node.js setup
│   ├── action.yml
│   ├── Dockerfile
│   ├── README.md
│── security-scan/      # Custom GitHub Action for security scanning
│   ├── action.yml
│   ├── scan.py
│   ├── README.md
│── LICENSE
│── README.md

Convenções de nomenclatura para arquivos e pastas

Para garantir a manutenção e a facilidade de uso, siga as convenções de nomenclatura consistentes.

Nomenclatura do repositório

  • Use nomes descritivos e consistentes para repositórios:
    • org-actions-repo
    • org-reusable-workflows
    • my-random-actions
  • Prefira nomes hifenizados para maior clareza:
    • ci-pipeline
    • CIPipeline

Nomenclatura de fluxo de trabalho e ação

  • Siga um formato estruturado:

    • [scope]-[purpose]
    • Exemplos:
      • ci-test.yml → para testes de integração contínua
      • deploy-app.yml Fluxo de trabalho de implantação
      • build-container.yml → cria contêineres do Docker

  • Use diretórios versionados para manutenção a longo prazo:

    reusable-workflows/
├── v1/
│   ├── ci-test.yml
│   ├── deploy-app.yml
├── v2/
│   ├── ci-test.yml
│   ├── deploy-app.yml

Nomenclatura de ação

  • Usar PascalCase ou kebab-case para nomes de ação:

    • Run-Linter
    • run-linter
    • Runlinter

  • Forneça descrições claras em action.yml:

    name: "Run Linter"
description: "A reusable action to run lint checks on JavaScript projects."

Planos para manutenção contínua de componentes reutilizáveis

1. Controle de versão e gerenciamento de dependência

  • Marcar versões usando lançamentos do GitHub (v1.0.0, v2.0.0).
  • Evite usar latest tags em fluxos de trabalho para evitar mudanças inesperadas que causem interrupções.
  • Usar o controle de versão semântico:
    • Atualizações de patch:v1.0.1 → Corrige bugs, atualizações secundárias.
    • Atualizações secundárias:v1.1.0 → novos recursos, compatíveis com versões anteriores.
    • Atualizações principais:v2.0.0 → Alterações interruptivas.

Referenciando versões em fluxos de trabalho

Em vez de:

uses: org-actions-repo/setup-node@latest

Use uma versão estável:

uses: org-actions-repo/setup-node@v1.2.0

2. Automatizando atualizações e manutenção

  • Implemente uma ação do GitHub para testar automaticamente fluxos de trabalho e ações antes de mesclar.
  • Use o Dependabot para detectar dependências desatualizadas em ações reutilizáveis.

3. Documentando e fornecendo diretrizes de uso

  • Cada repositório deve incluir:
    • README.md explicando:
      • Finalidade do componente.
      • Como usar.
      • Exemplo de fluxos de trabalho.
    • CHANGELOG.md para acompanhar as atualizações.
    • CONTRIBUTING.md detalha as práticas recomendadas para modificações.

4. Controle de segurança e acesso

  • Restrinja o acesso de gravação a repositórios de ações.
  • Exigir revisões de código e CODEOWNERS do GitHub para gerenciar alterações.
  • Use Escaneamento de segredos do GitHub para evitar a codificação de segredos em fluxos de trabalho.

5. Estratégia de monitoramento e descontinuação

  • Configure problemas e discussões do GitHub para comentários.
  • Plano de substituição:
    • Notifique os usuários antes de remover versões mais antigas.
    • Oferecer guias de migração para alterações importantes.

Como distribuir ações para uma empresa

O GitHub Actions habilita a automação de fluxos de trabalho, como teste, implantação e verificação de segurança. Em uma empresa, a distribuição de ações com eficiência permite que várias equipes reutilizem tarefas comuns de automação em vez de reinventar os mesmos fluxos de trabalho.

Há três métodos principais para distribuir o GitHub Actions em uma empresa:

  1. Ações de publicação no GitHub Marketplace (para distribuição pública).
  2. Ações de hospedagem em repositórios de Organization-Owned (para distribuição corporativa interna).
  3. Usando pacotes do GitHub para distribuir ações em contêineres (para distribuição mais controlada).

Práticas recomendadas para distribuir ações em uma empresa

Melhor prática Recomendação
Padronização Mantenha um único repositório para ações reutilizáveis com documentação clara.
Controle de versão Use controle de versão semântico (v1.0.0, v2.0.0) e evite latest para estabilidade.
Revisões de segurança Exigir revisões de código e verificações de segurança automatizadas antes de publicar ações.
Controle de acesso Restrinja quem pode modificar e usar ações internas por meio de configurações de repositório.
Atualizações regulares Mantenha um registro de alterações e notifique os usuários sobre as atualizações para evitar mudanças disruptivas.

Comparação de métodos de distribuição

Método Caso de uso Controle de acesso Considerações sobre segurança
GitHub Marketplace Distribuição pública Sem restrições Acessível publicamente, deve ser seguro
Repositórios de propriedade da organização Uso interno da empresa Equipes e funções de repositório Requer um controle de permissão estrito
Pacotes do GitHub (ações contêinerizadas) Uso interno seguro Autenticação necessária As imagens devem ser protegidas contra adulteração

Escolher o método correto depende de requisitos de negócios, necessidades de segurança e considerações de escalabilidade. As empresas devem implementar uma abordagem estruturada para distribuir o GitHub Actions, garantindo eficiência, segurança e conformidade em seus fluxos de trabalho de DevOps.