GitHub Actions CI: pipeline de build e testes do zero

O celular vibra. Chega uma mensagem de um colega: “O ambiente de produção caiu. Aquele código que você integrou ontem está com problema.”

Dá um frio na barriga. Mas os testes tinham passado localmente, certo? Depois de vasculhar os logs, você descobre que o Node local estava na versão 20, enquanto o ambiente de testes usava a 18. O comportamento diferente de uma API causou o bug. Naquele momento, só dá vontade de reclamar: se uma pipeline de CI tivesse executado os testes automaticamente antes do merge, isso nunca teria acontecido.

Executar testes manualmente é o tipo de tarefa que nove entre dez desenvolvedores esquecem. O décimo provavelmente só lembra porque já sofreu com isso. É justamente esse problema que o GitHub Actions resolve: depois de um push, ele faz build, testes e implantação automaticamente. Você não precisa ficar acompanhando; a máquina cuida do trabalho.

Aqui vamos montar uma pipeline completa de CI do zero. O percurso inclui um modelo de workflow pronto para copiar, a estratégia Matrix para testar várias versões em paralelo — capaz de cortar o tempo de build pela metade — e problemas reais com suas soluções. Vamos começar.

Capítulo 1: primeiros passos com GitHub Actions

O que é GitHub Actions

Em poucas palavras, GitHub Actions é a plataforma de automação integrada ao GitHub. Você faz um push local, e ela executa testes, builds e implantações na nuvem, tudo de forma automática.

Antes, para implementar CI/CD, era preciso manter um servidor Jenkins; configurar, atualizar e administrar tudo dava trabalho. O diferencial do GitHub Actions é dispensar servidor próprio e instalação de software: basta colocar um arquivo YAML no repositório. Além disso, ele oferece 2.000 minutos gratuitos por mês, sem limite para repositórios públicos, o que atende bem a projetos pessoais e equipes pequenas.

Em comparação com Jenkins e Travis CI, o GitHub Actions tem vantagens claras: integração profunda com repositórios GitHub, status do build visível diretamente no PR, configuração simples sem a necessidade de aprender a sintaxe Groovy e um ecossistema amplo, com dezenas de milhares de Actions prontas no Marketplace oficial. Também há desvantagens: a solução fica vinculada ao GitHub, e uma migração para GitLab exige reescrever a configuração; em pipelines empresariais complexas, Jenkins ainda pode ser mais flexível. Para a maioria dos projetos, porém, GitHub Actions é suficiente.

Visão geral dos conceitos principais

Quem está começando com GitHub Actions pode se confundir com alguns conceitos. Vamos explicá-los de forma direta:

Workflow (fluxo de trabalho): um arquivo YAML que define todo um processo automatizado. Por exemplo, “executar testes sempre que houver um push na branch main” é um workflow. O arquivo fica no diretório .github/workflows/.

Job (tarefa): um conjunto de etapas dentro do workflow. Vários Jobs podem ser executados em paralelo ou ter dependências entre si. Por exemplo, primeiro executar o Job de “testes” e depois o de “implantação”.

Step (etapa): uma operação específica dentro de um Job, executada em sequência. Pode ser um comando, como npm test, ou uma Action criada por outra pessoa, como actions/checkout@v4.

Runner (executor): a máquina virtual que executa o Job. O GitHub oferece três opções: ubuntu-latest (Linux), windows-latest (Windows) e macos-latest (macOS). Também é possível usar um servidor próprio, mas os Runners oficiais atendem à maioria dos casos.

Uma analogia: o Workflow é o roteiro, os Jobs são as cenas, os Steps são as ações de cada cena e o Runner é o ator que as executa.

Seu primeiro workflow de CI

Não complique: primeiro faça funcionar. Na raiz do projeto, crie .github/workflows/ci.yml e cole o código abaixo:

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

name: CI Pipeline  # Nome do workflow, exibido na página GitHub Actions

on:
  push:
    branches: [main]  # Aciona em um push para a branch main
  pull_request:
    branches: [main]  # Aciona quando o PR aponta para a branch main

permissions:
  contents: read  # Menor privilégio: concede apenas permissão de leitura

jobs:
  build:
    runs-on: ubuntu-latest  # Usa o ambiente Ubuntu mais recente
    timeout-minutes: 15     # Limite de tempo para evitar travamentos

    steps:
      - name: Checkout code
        uses: actions/checkout@v4  # Baixa o código

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20   # Usa Node.js 20
          cache: 'npm'        # Ativa o cache do npm

      - name: Install dependencies
        run: npm ci          # Instala dependências; ci é mais rápido e confiável que install

      - name: Run tests
        run: npm test        # Executa os testes

      - name: Build
        run: npm run build   # Faz o build

O que esse código faz?

A primeira parte, on, define os gatilhos: o workflow é acionado quando há um push para main ou quando um PR aponta para main. A segunda, permissions, declara as permissões. Seguindo o princípio do menor privilégio, ela concede apenas contents: read, impedindo que o workflow modifique o repositório por engano. A terceira é o núcleo: um Job chamado build, executado no Ubuntu, que baixa o código, instala o Node e as dependências, roda os testes e faz o build, nessa ordem.

Faça o commit desse código, envie-o ao GitHub e abra a página Actions do repositório. Você verá um pequeno círculo verde girando: é o Runner executando o workflow. Após alguns minutos, se todas as etapas mostrarem uma marca verde, parabéns: sua primeira pipeline de CI está funcionando.

E se aparecer uma marca vermelha? Abra a execução e consulte os logs; a saída de cada etapa está detalhada ali. Em 90% dos casos, o problema é uma falha na instalação das dependências ou nos próprios testes, não na configuração da CI.

Capítulo 2: configurações fundamentais da pipeline de CI

O workflow do primeiro capítulo já funciona, mas ainda falta bastante para ficar realmente útil. Agora vamos tratar de quatro configurações fundamentais: gatilhos, permissões, variáveis de ambiente e cache de dependências. Elas formam a estrutura da pipeline de CI e, quando bem configuradas, tornam o workflow mais seguro e eficiente.

Gatilhos: quando executar

Os gatilhos definem quando o workflow começa. Os dois mais usados são push e pull_request.

on:
  push:
    branches: [main, dev]    # Aciona em um push para main ou dev
    paths:
      - 'src/**'             # Aciona somente quando mudam arquivos em src
      - 'package.json'       # Também aciona quando package.json muda
  pull_request:
    branches: [main]         # Aciona quando o PR aponta para main

O filtro paths é especialmente útil. Se o projeto tiver um diretório de documentação, como docs/, uma alteração nos documentos não deveria acionar a CI. Com paths, apenas mudanças no código executam o build, economizando recursos e tempo.

Além de push e PR, existem outras formas de acionamento:

schedule: tarefa agendada com uma expressão cron. Por exemplo, para executar um build uma vez por dia, de madrugada:

on:
  schedule:
    - cron: '0 0 * * *'  # Todos os dias à 0h UTC (8h no horário de Pequim)

Em um dos meus projetos, uso isso para verificar dependências periodicamente: todos os dias, o workflow executa npm outdated, identifica pacotes desatualizados e envia um aviso por e-mail.

workflow_dispatch: acionamento manual. Às vezes você quer executar um build sem fazer um push, por exemplo para testar uma configuração. Essa opção adiciona o botão “Run workflow” à página Actions; basta clicar para iniciar a execução.

on:
  workflow_dispatch:  # Acionamento manual, sem configuração adicional

Gerenciamento de permissões: segurança em primeiro lugar

Por padrão, GitHub Actions fornece ao workflow um GITHUB_TOKEN. Esse token pode ler e gravar no repositório, criar PRs e até enviar código. Parece prático, mas também cria um risco: se alguém explorar o workflow, poderá obter permissão de gravação no repositório.

Em 2021, um incidente de segurança afetou o workflow de CI de um projeto de código aberto: um invasor enviou código malicioso por meio de um PR forjado. A lição foi dura. Por isso, hoje o GitHub recomenda um princípio: declare explicitamente o menor privilégio necessário.

permissions:
  contents: read    # Pode apenas ler o conteúdo do repositório
  pull-requests: write  # Declare separadamente se precisar criar um PR

Para uma pipeline de CI comum, que apenas executa testes e builds, contents: read é suficiente. Se o workflow precisar publicar uma Release, comentar em um PR ou realizar outra operação, adicione somente a permissão correspondente.

Uma dica prática: nas configurações do repositório, altere a permissão padrão para “Read repository contents permission”. Assim, todos os workflows começam apenas com acesso de leitura, e aqueles que realmente precisam gravar devem declarar isso. É uma camada extra de proteção.

Variáveis de ambiente: gerenciamento por nível

As variáveis de ambiente têm três níveis: workflow, job e step. Quanto mais baixo o nível, menor o escopo; uma variável em um nível inferior pode substituir o valor definido acima.

env:
  NODE_ENV: production     # Nível do workflow, disponível para todos os jobs
  CI: true                 # Muitas ferramentas ajustam o comportamento ao detectar esta variável

jobs:
  build:
    env:
      BUILD_TARGET: web    # Nível do job, disponível apenas no job build

    steps:
      - name: Run custom script
        env:
          MY_VAR: hello    # Nível do step, disponível apenas nesta etapa
        run: echo $MY_VAR

Por que usar níveis? Imagine que o projeto tenha vários Jobs, como build e deploy. Ambos precisam de NODE_ENV, então ela fica no nível do workflow. Apenas o Job build usa BUILD_TARGET, por isso essa variável fica no nível do job. Se uma única etapa precisar de uma variável temporária, por exemplo um parâmetro para um script, ela deve ficar no nível do step.

E como lidar com informações sensíveis? Nunca as escreva diretamente no YAML. O GitHub oferece Secrets: adicione a chave, como API_KEY, nas configurações do repositório e faça referência a ela no workflow usando ${{ secrets.API_KEY }}. Os Secrets são ocultados automaticamente nos logs e não ficam expostos.

steps:
  - name: Deploy to server
    env:
      SSH_KEY: ${{ secrets.SSH_KEY }}  # Referência a um Secret
    run: |
      echo "$SSH_KEY" > private.key
      ssh -i private.key user@server 'deploy.sh'

Cache de dependências: acelerar o build

Se o projeto tiver muitas dependências, como centenas de pacotes npm, instalá-las do zero em cada execução da CI demora bastante. Em um dos meus projetos, instalar dependências levava 3 minutos, enquanto os testes levavam 1 minuto: 75% do tempo era gasto apenas na instalação.

GitHub Actions oferece um mecanismo de cache que armazena as dependências instaladas para reutilizá-las na próxima execução. A maneira mais simples é usar o cache integrado do setup-node.

- uses: actions/setup-node@v4
  with:
    node-version: 20
    cache: 'npm'  # Armazena automaticamente o cache das dependências npm

Com uma única linha, cache: 'npm', a primeira execução instala as dependências normalmente e salva node_modules no cache. Na segunda, se package-lock.json não tiver mudado, os arquivos são recuperados do cache, reduzindo a instalação de 3 minutos para 10 segundos.

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

Se você usa pnpm ou yarn, altere o valor para cache: 'pnpm' ou cache: 'yarn'.

Para um controle mais preciso, use actions/cache:

- name: Cache dependencies
  uses: actions/cache@v4
  with:
    path: ~/.npm         # Diretório global de cache do npm
    key: npm-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
    restore-keys: |
      npm-${{ runner.os }}-

key é o identificador exclusivo do cache. Neste caso, ele usa o hash de package-lock.json: se o arquivo de lock mudar, o cache é invalidado e as dependências são instaladas novamente. restore-keys funciona como alternativa: se não houver correspondência exata, ele procura um cache semelhante e recupera o que for possível.

Quando a taxa de acerto do cache é alta, o build fica consideravelmente mais rápido. Em um dos meus projetos, ele levou 4 minutos sem cache e 1,5 minuto com cache. Com 20 builds por dia, o tempo economizado já dá para escrever um artigo inteiro.

Capítulo 3: estratégia Matrix para testes paralelos

Este é o recurso do GitHub Actions que eu mais gosto e também o principal diferencial deste artigo. A estratégia Matrix transforma um Job em vários Jobs paralelos para testar diferentes versões e sistemas operacionais. Um único push pode iniciar dezenas de builds em poucos segundos, todos em paralelo, reduzindo o tempo total pela metade ou mais em comparação com uma execução sequencial.

O que é Matrix

Imagine que você precise testar o projeto nas versões 16, 18 e 20 do Node. A abordagem tradicional seria escrever três Jobs ou alternar as versões em sequência dentro de um único Job. A primeira opção repete configuração; a segunda demora muito mais.

Matrix funciona como uma tabela: o eixo horizontal representa as versões do Node, o vertical representa os sistemas operacionais e cada célula é uma tarefa de teste independente. GitHub Actions gera automaticamente todas as combinações e as executa em paralelo.

strategy:
  matrix:
    node: [16, 18, 20]
    os: [ubuntu-latest, windows-latest]

Essa configuração gera seis Jobs: Node 16 no Ubuntu, Node 16 no Windows, Node 18 no Ubuntu e assim por diante. O tempo total corresponde ao Job mais lento, e não à soma de todos eles.

Matriz de versões: testar várias versões do Node

Um dos meus projetos teve exatamente este problema: o desenvolvimento usava Node 20, mas um usuário relatou que o programa não funcionava no Node 18. Depois de investigar, descobri que uma API se comportava de maneira diferente nessa versão. Se os testes em várias versões já existissem, o bug não teria sido publicado.

Usar Matrix para testar várias versões é simples:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false    # Se uma versão falhar, as demais continuam
      matrix:
        node-version: [16, 18, 20, 22]  # Testa estas quatro versões

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}  # Usa dinamicamente a versão do Matrix
          cache: 'npm'
      - run: npm ci
      - run: npm test

Os pontos principais são:

• matrix.node-version define a lista de versões que serão testadas
• ${{ matrix.node-version }} referencia o valor dentro de steps; cada Job recebe uma versão diferente
• fail-fast: false permite que as demais versões continuem mesmo se uma delas falhar. O padrão é true, que interrompe todas as execuções quando ocorre uma falha. Para testes de compatibilidade, é melhor desativá-lo para ver o resultado de todas as versões.

include e exclude: quando algumas combinações não precisam ser testadas ou exigem configuração adicional, use essas duas palavras-chave.

strategy:
  matrix:
    node-version: [16, 18, 20]
    os: [ubuntu-latest, windows-latest]
    exclude:
      - node-version: 16      # Não testa a combinação Node 16 + Windows
        os: windows-latest
    include:
      - node-version: 20      # Executa mais um teste do Node 20 no macOS
        os: macos-latest

exclude remove as combinações desnecessárias, enquanto include adiciona combinações extras. Isso permite controlar o escopo dos testes com flexibilidade.

Matriz de sistemas operacionais: testes multiplataforma

Se o projeto pode ser executado em diferentes sistemas operacionais, como uma ferramenta de linha de comando, a matriz de sistemas é muito útil.

jobs:
  test:
    runs-on: ${{ matrix.os }}  # Define dinamicamente o sistema operacional
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node-version: [18, 20]

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
      - run: npm ci
      - run: npm test

Alguns pontos merecem atenção:

Diferenças entre plataformas: caminhos de arquivos são diferentes no Windows e no Linux (\ em comparação com /), e algumas ferramentas de linha de comando também se comportam de outra forma. Os testes multiplataforma ajudam a encontrar esses problemas antes.

Controle de custos: GitHub Actions cobra valores diferentes conforme o sistema operacional. O Linux oferece 2.000 minutos gratuitos por mês; o Windows consome o dobro de minutos do Linux, e o macOS, dez vezes mais. Se você testar em um Runner macOS, a cota mensal acaba rapidamente.

Estratégias para economizar:

• Teste no macOS somente quando necessário, como em um projeto que realmente será usado nesse sistema
• Coloque os testes de macOS em um workflow separado e acione-os manualmente com workflow_dispatch
• Repositórios públicos não têm esse limite; se o projeto puder ser público, considere essa opção

Técnicas para melhorar o desempenho

Matrix permite paralelismo, mas ele não é ilimitado. O GitHub restringe a quantidade padrão de execuções paralelas para evitar o esgotamento de recursos. Você também pode controlá-la manualmente:

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

strategy:
  max-parallel: 4  # Executa no máximo 4 Jobs simultaneamente
  matrix:
    node-version: [16, 18, 20, 22]

Se o Matrix gerar muitas combinações, como mais de dez Jobs, max-parallel evita iniciar tudo de uma vez e reduz o consumo da cota gratuita.

Acelerar com acertos de cache: cada Job do Matrix tem seu próprio cache. O parâmetro cache de setup-node cuida disso automaticamente, sem configuração adicional. O ponto principal é que, quando package-lock.json e node-version permanecem estáveis, a taxa de acerto do cache tende a ser alta.

Remover etapas desnecessárias: algumas etapas são repetidas em todos os Jobs do Matrix, embora isso nem sempre seja necessário. A análise de código com lint, por exemplo, normalmente não precisa ser testada em várias versões:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - run: npm ci
      - run: npm run lint  # Executa o lint uma única vez no Node 20

  test:
    needs: lint  # Executa test somente depois que lint tiver sucesso
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [16, 18, 20]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
      - run: npm ci
      - run: npm test

Dessa forma, lint é executado uma vez, enquanto test é executado em três versões. O resultado é mais eficiente.

Dados reais: em um dos meus projetos, testar três versões em sequência levava 12 minutos sem Matrix. Com Matrix em paralelo, o tempo total caiu para 4 minutos, determinado pelo Job mais lento. São 8 minutos economizados; com dez builds por dia, a economia mensal já dá para assistir a um filme inteiro.

Capítulo 4: experiência prática e solução de problemas

Os três primeiros capítulos mostraram como configurar uma pipeline de CI. Agora reuni uma lista de consulta rápida em três áreas: segurança, desempenho e solução de problemas. Quando algo falhar, volte a esta seção para economizar tempo.

Checklist prático de segurança

O último item é frequentemente ignorado: a referência à versão de uma Action. Actions oficiais costumam usar tags como @v4, o que facilita atualizações. Mas uma tag pode ser alterada; em teoria, alguém poderia apontar @v4 para código malicioso. Referenciar um SHA, como @b4ffde65f..., dificulta atualizações, mas é mais seguro. Para projetos em produção, vale a pena usar SHA.

Checklist para melhorar o desempenho

concurrency é muito útil: se você fizer cinco pushes seguidos na mesma branch, o padrão é iniciar cinco builds. Com essa configuração, os quatro anteriores são cancelados, e apenas o último continua.

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true  # Cancela o build antigo que ainda está em execução

Tabela de consulta rápida para problemas comuns

Veja como lidar com alguns cenários frequentes:

Tempo limite de rede: às vezes, o GitHub Runner se conecta lentamente ao npm registry. É possível configurar um espelho no arquivo .npmrc:

- name: Configure npm registry
  run: echo "registry=https://registry.npmmirror.com" > .npmrc

Memória insuficiente: durante o build de projetos grandes, o Node pode esgotar a memória. Adicione uma variável de ambiente:

env:
  NODE_OPTIONS: --max_old_space_size=4096  # Aloca 4 GB de memória para o Node

Cache não funciona: é normal não haver cache na primeira execução. Confirme que package-lock.json existe, pois npm ci precisa do arquivo de lock, e que o parâmetro cache de setup-node corresponde ao gerenciador de pacotes usado, como npm, pnpm ou yarn.

Conclusão

Depois de todos esses detalhes, os pontos principais são poucos: um único arquivo YAML monta a pipeline de CI; as permissões devem seguir o princípio do menor privilégio; as variáveis de ambiente são organizadas em três níveis; o cache de dependências pode cortar pela metade o tempo de instalação; e Matrix simplifica os testes paralelos em várias versões.

Copie o modelo de workflow do primeiro capítulo, ajuste a versão do Node e os comandos do projeto e adicione CI ao seu repositório. Primeiro faça funcionar; depois, refine a configuração aos poucos. Vale a pena experimentar Matrix, mesmo com apenas duas versões do Node. Ver várias marcas verdes aparecerem ao mesmo tempo deixa bem clara a eficiência dos testes paralelos.

Se você tiver algum problema ao usar GitHub Actions, deixe um comentário. Vou acrescentar as dúvidas mais comuns à tabela de consulta rápida do quarto capítulo para ajudar mais pessoas a evitar os mesmos erros.