GitHub Actions: boas práticas

Este documento de trabalho reúne um conjunto de boas práticas para usar o GitHub Actions. Se você tiver sugestões ou acréscimos, abra um pull request no GitHub!

• GitHub Actions: boas práticas
  • Coletânea de boas práticas
    • Defina tempos limite para os fluxos de trabalho
      • Exemplo
    • Considere se as actions (de terceiros) são realmente necessárias
    • Limite o escopo do token do fluxo de trabalho
      • Exemplo
    • Fixe as actions em SHAs
      • Encontrando o SHA do commit
      • Exemplo
    • Fixe os test runners em uma versão
      • Exemplo
    • Considere configurar uma estratégia de concorrência
      • Exemplo
    • Considere quais gatilhos são realmente necessários
    • Leia o guia "Security hardening for GitHub Actions"
  • Checklist do fluxo de trabalho

Coletânea de boas práticas

Defina tempos limite para os fluxos de trabalho

Por padrão, o GitHub Actions encerra os fluxos de trabalho depois de 6 horas, caso eles não tenham terminado até lá. Muitos fluxos de trabalho não precisam nem de perto de tanto tempo para terminar, mas às vezes acontecem erros inesperados ou um job trava até que a execução do fluxo de trabalho seja encerrada 6 horas depois de começar. Por isso, é recomendável especificar um tempo limite menor.

O tempo limite ideal depende de cada fluxo de trabalho, mas 30 minutos costuma ser mais do que suficiente para os fluxos de trabalho usados nos repositórios do Exercism.

Isso tem as seguintes vantagens:

• Os PRs não ficarão metade do dia com a CI pendente, problemas podem ser detectados cedo ou as execuções do fluxo de trabalho podem ser reiniciadas.
• O número total de builds em paralelo é limitado; jobs travados não causarão problemas para outros PRs se forem cancelados cedo.

Exemplo

jobs:
  configlet:
    timeout-minutes: 30
    runs-on: ubuntu-latest
    steps:
      - [...]

Considere se as actions (de terceiros) são realmente necessárias

As actions devem ser tratadas como dependências da sua linguagem de programação preferida¹: elas são código escrito por autores terceiros, fora do controle do Exercism. Mesmo que você confie nos autores da action, pode haver uma tomada hostil do repositório, o que dará indiretamente a essas pessoas acesso aos repositórios do Exercism, incluindo permissão de escrita.

Por isso, considere com cuidado se vale mesmo a pena introduzir uma nova action ou se é melhor mover o código para uma action (nova) sob o controle do Exercism.

Considere também se a action é mantida ativamente, por exemplo verificando a atividade recente do repositório ou confirmando que a action faz parte de uma organização, e não de uma conta individual.

Actions publicadas pelo GitHub ou pela organização do Exercism podem, em geral, ser consideradas razoavelmente seguras para incluir sem cuidado especial.

Limite o escopo do token do fluxo de trabalho

Por padrão, o token de acesso concedido ao fluxo de trabalho tem permissões amplas, tanto de leitura quanto de escrita.

O princípio do menor privilégio também deve ser aplicado aos fluxos de trabalho.

Você pode especificar de quais permissões um fluxo de trabalho precisa em cada fluxo de trabalho.

Exemplo

Se um fluxo de trabalho só precisa ler o conteúdo de um repositório, mas não escrever nele, por exemplo porque é uma verificação de CI comum, você pode restringir o token assim:

permissions:
  contents: read

Consulte a documentação do GitHub para ver a lista completa de permissões.

Fixe as actions em SHAs

Ao usar outras actions, fixe-as em um commit (pelo SHA), não em um branch ou uma tag. Isso garante que o mesmo código será executado sempre, o que não é garantido quando você fixa em um branch ou uma tag.

Isso traz dois benefícios:

1. Torna a sua build estável
2. Impede que um invasor altere um branch ou uma tag para apontar para código malicioso

A única exceção a essa regra podem ser as actions que nós (o Exercism) criamos.

Encontrando o SHA do commit

Normalmente, você quer fixar no SHA do commit de uma release específica. Para encontrar o SHA do commit de uma release, vá até a página de releases do repositório da action (por exemplo, https://github.com/actions/checkout/releases). Encontre a release que você quer usar e clique no SHA abreviado (por exemplo, a12a394) listado na seção de resumo à esquerda da release. Você será então redirecionado para a página de detalhes da release, que mostra o SHA completo do commit que você pode usar.

Exemplo

- name: Checkout code
  uses: actions/checkout@a12a3943b4bdde767164f792f33f40b04645d846

Fixe os test runners em uma versão

A maioria dos fluxos de trabalho roda nos runners compatíveis do GitHub. Ao usar um desses runners, use uma versão específica em vez da versão mais recente.

Isso garante que o fluxo de trabalho sempre rodará no mesmo runner, o que torna a sua build estável.

Exemplo

Use:

runs-on: ubuntu-22.04

em vez de:

runs-on: ubuntu-latest

Considere configurar uma estratégia de concorrência

Muitas vezes não é necessário nem útil rodar a CI em commits intermediários se um commit mais novo foi enviado nesse meio tempo.

Você pode configurar uma estratégia de concorrência para cancelar automaticamente os fluxos de trabalho em execução no mesmo contexto.

Exemplo

Para cancelar builds intermediárias em um PR, você pode usar as seguintes configurações de concorrência:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}

Considere quais gatilhos são realmente necessários

Leia o guia "Security hardening for GitHub Actions"

As práticas mencionadas acima não são, de forma alguma, exaustivas. Para um guia completo sobre boas práticas de segurança para usar o GitHub Actions com segurança, confira o guia de segurança do GitHub.

Checklist do fluxo de trabalho

Você pode usar o checklist a seguir para verificar se um fluxo de trabalho segue as boas práticas. O checklist não tem a intenção de ser completo, mas sim de focar nos itens mais importantes.