GitHub Actions: boas práticas

Este documento em evolução reúne um conjunto de boas práticas para usar o GitHub Actions. Se tiveres sugestões ou quiseres acrescentar algo, abre um pull request no GitHub!

• GitHub Actions: boas práticas
  • Conjunto de boas práticas
    • Define timeouts para os fluxos de trabalho
      • Exemplo
    • Pensa se as actions (de terceiros) são realmente necessárias
    • Limita o âmbito do token do fluxo de trabalho
      • Exemplo
    • Fixa as actions a SHAs
      • Encontrar o SHA do commit
      • Exemplo
    • Fixa a versão dos runners de testes
      • Exemplo
    • Considera configurar uma estratégia de concorrência
      • Exemplo
    • Considera quais os triggers que são realmente necessários
    • Lê o guia "Security hardening for GitHub Actions"
  • Lista de verificação do fluxo de trabalho

Conjunto de boas práticas

Define timeouts para os fluxos de trabalho

Por predefinição, o GitHub Actions termina os fluxos de trabalho ao fim de 6 horas, se ainda não tiverem acabado nessa altura. Muitos fluxos de trabalho não precisam de nem metade desse tempo para terminar, mas por vezes surgem erros inesperados ou um job fica bloqueado até a execução do fluxo de trabalho ser terminada 6 horas depois de ter começado. Por isso, recomenda-se que especificares um timeout mais curto.

O timeout ideal depende de cada fluxo de trabalho, mas 30 minutos costumam ser mais do que suficientes para os fluxos de trabalho usados nos repositórios do Exercism.

Isto tem as seguintes vantagens:

• Os PRs não ficam pendentes à espera da CI meio dia, os problemas são detetados mais cedo e as execuções do fluxo de trabalho podem ser reiniciadas.
• O número total de builds paralelas é limitado, e os jobs bloqueados não causam problemas a outros PRs se forem cancelados cedo.

Exemplo

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

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

As actions devem ser tratadas como dependências na tua linguagem de programação preferida¹: são código escrito por autores externos, fora do controlo do Exercism. Mesmo que confies nos autores da action, pode haver uma tomada hostil do repositório, que dá indiretamente a essas pessoas acesso aos repositórios do Exercism, incluindo permissões de escrita.

Por isso, deves ponderar bem se vale a pena introduzir uma nova action ou se é melhor passar o código para uma action (nova) sob o controlo do Exercism.

Vê também se a action tem manutenção ativa, por exemplo verificando a atividade recente do repositório ou confirmando que a action pertence a uma organização e não a uma conta individual.

As actions publicadas pelo GitHub ou pela organização do Exercism podem, em geral, ser consideradas mais ou menos seguras para incluir sem cuidados especiais.

Limita o âmbito do token do fluxo de trabalho

Por predefinição, o token de acesso concedido ao fluxo de trabalho tem permissões muito amplas, tanto de leitura como de escrita.

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

Podes especificar, caso a caso, de que permissões um fluxo de trabalho precisa.

Exemplo

Se um fluxo de trabalho só precisa de ler o conteúdo de um repositório mas não de escrever nele, por exemplo porque é uma verificação normal de CI, podes restringir o token da seguinte forma:

permissions:
  contents: read

Consulta a documentação do GitHub para veres a lista completa de permissões.

Fixa as actions a SHAs

Quando usas outras actions, fixa-as a um commit (através do respetivo SHA), não a um ramo ou a uma tag. Assim garantes que é sempre executado o mesmo código, o que não está garantido quando fixas a um ramo ou a uma tag.

Isto traz duas vantagens:

1. Torna a tua build estável.
2. Impede que um atacante altere um ramo ou uma tag para apontar para código malicioso.

A única exceção a esta regra podem ser as actions que nós (o Exercism) criámos.

Encontrar o SHA do commit

Normalmente queres fixar ao SHA do commit de uma release específica. Para encontrares o SHA do commit de uma release, vai à página de releases do repositório da action (por exemplo, https://github.com/actions/checkout/releases). Encontra a release que queres usar e clica no SHA abreviado (por exemplo, a12a394) apresentado na secção de resumo à esquerda da release. Vais ser redirecionado para a página de detalhes da release, onde está o SHA completo do commit que podes usar.

Exemplo

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

Fixa a versão dos runners de testes

A maioria dos fluxos de trabalho corre nos runners suportados pelo GitHub. Quando usas um destes runners, usa uma versão específica em vez da versão mais recente.

Assim garantes que o fluxo de trabalho corre sempre no mesmo runner, o que torna a tua build estável.

Exemplo

Usa:

runs-on: ubuntu-22.04

em vez de:

runs-on: ubuntu-latest

Considera configurar uma estratégia de concorrência

Muitas vezes não é necessário nem útil correr a CI em commits intermédios se, entretanto, já foi enviado um commit mais recente.

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

Exemplo

Para cancelar builds intermédias num PR, podes usar as seguintes definições de concorrência:

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

Considera quais os triggers que são realmente necessários

Lê 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 em segurança, consulta o guia de segurança do GitHub.

Lista de verificação do fluxo de trabalho

Podes usar a lista de verificação seguinte para verificar se um fluxo de trabalho segue as boas práticas. A lista não pretende ser exaustiva; foca-se nos pontos mais importantes.