Como criar um workflow no GitHub Actions para rodar testes automaticamente

Sim. Você pode criar um workflow no GitHub Actions para instalar as dependências e rodar os testes do projeto automaticamente a cada push ou pull request. O arquivo fica dentro de .github/workflows e usa YAML para dizer ao GitHub quando executar e quais comandos chamar.

Neste guia, vamos montar uma automação para um projeto Node.js. Ela fará quatro coisas: baixar o código, preparar o Node, instalar as dependências com o lockfile e executar o script de testes. Assim, um erro básico deixa de chegar ao repositório principal por distração ou pressa.

O que é um workflow do GitHub Actions?

Workflow é um processo automatizado descrito em um arquivo YAML. Ele pode ser disparado por eventos como push, abertura de pull request ou execução manual. Cada workflow tem um ou mais jobs, e cada job é executado em uma máquina chamada runner.

Pense no runner como um computador temporário alugado pelo GitHub para aquela execução. Ele baixa o projeto, roda os comandos e registra o resultado na aba Actions. Quando a execução termina, não conte com os arquivos que ficaram naquela máquina para a próxima rodada.

Isso é útil para integração contínua (CI): toda alteração passa por uma checagem repetível antes de ser incorporada. O GitHub explica esse fluxo no guia oficial de início rápido do Actions.

O que você precisa antes de começar

• um repositório no GitHub;
• um projeto Node.js com package.json;
• um script chamado test em package.json;
• um arquivo package-lock.json versionado no repositório;
• permissão para criar arquivos e workflows no projeto.

O package-lock.json não é um detalhe decorativo. Ele registra as versões resolvidas das dependências e permite que o comando npm ci instale uma árvore mais previsível. Se o seu projeto usa Yarn ou pnpm, o fluxo é parecido, mas o gerenciador e o arquivo de lock precisam ser trocados.

Como criar o workflow para rodar testes

1. Crie a pasta do workflow

Na raiz do repositório, crie a pasta .github/workflows. Dentro dela, crie um arquivo chamado, por exemplo, testes.yml. O GitHub só descobre automaticamente workflows salvos nesse diretório; o nome do arquivo pode ser outro, desde que termine em .yml ou .yaml.

2. Cole o arquivo YAML

Use este exemplo como ponto de partida:

name: Testes

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: Baixar o código
        uses: actions/checkout@v7

      - name: Preparar o Node.js
        uses: actions/setup-node@v7
        with:
          node-version: 22
          cache: npm

      - name: Instalar dependências
        run: npm ci

      - name: Rodar testes
        run: npm test

As versões v7 usadas no exemplo correspondem às versões mais recentes consultadas nas páginas de releases das ações oficiais actions/checkout e actions/setup-node em 26 de agosto de 2026. Tags de ação podem mudar no futuro; em ambientes mais sensíveis, vale fixar cada ação em um commit SHA revisado pela equipe.

3. Faça o commit do arquivo

Salve o arquivo, faça commit e envie para o GitHub:

git add .github/workflows/testes.yml
git commit -m "Adiciona testes automáticos"
git push origin main

O evento push dispara o workflow quando o commit chega à branch main. Se você abrir uma pull request direcionada a essa branch, o evento pull_request também fará a verificação.

Entenda cada parte do arquivo

• name: nome exibido na aba Actions.
• on: eventos que iniciam a execução. Neste caso, push e pull request para main.
• permissions: reduz o acesso padrão do GITHUB_TOKEN para leitura do conteúdo. É uma proteção simples contra permissões exageradas.
• runs-on: sistema usado pelo runner. ubuntu-latest pede um runner Linux hospedado pelo GitHub.
• uses: chama uma action pronta. checkout baixa o repositório e setup-node prepara o Node.
• run: executa um comando no ambiente do runner.

O manual de sintaxe dos workflows detalha filtros de branch, eventos, jobs, matrizes e permissões. O ponto mais importante para começar é separar o gatilho do trabalho: on decide quando rodar, enquanto jobs define o que será feito.

Como confirmar se o workflow funcionou

Abra o repositório no GitHub e clique em Actions. Escolha o workflow “Testes” e abra a execução mais recente. Uma marca verde indica que todos os passos terminaram bem; um X vermelho mostra em qual passo o processo parou.

Para testar também o caminho de falha, altere um teste de propósito e envie outro commit. O objetivo não é apenas ver uma execução verde: é confirmar que o workflow realmente impede a aprovação quando o comando npm test retorna erro.

Se o projeto usa uma versão de Node diferente, troque o valor de node-version. O ideal é alinhar essa versão ao arquivo de configuração do projeto, como .nvmrc, ou à versão usada localmente pela equipe. Um workflow que usa Node 22 enquanto todo mundo desenvolve com outra versão pode criar uma falsa sensação de segurança.

Erros comuns e como corrigir

“npm ci” falha por causa do lockfile

Isso costuma acontecer quando o package-lock.json não existe, não está no commit ou foi gerado com uma versão incompatível do npm. Gere o lockfile localmente com a versão de Node usada pelo projeto, faça commit e tente novamente. Usar npm install pode mascarar diferenças entre instalações e não é a melhor primeira correção.

O comando “npm test” não existe

Confira a seção scripts do package.json. Se o projeto usa outro nome, como npm run test:unit, substitua o comando no workflow. O GitHub não sabe quais testes você espera: ele apenas executa o que foi escrito no YAML.

O workflow não aparece na aba Actions

Verifique se o caminho está exatamente em .github/workflows, se a extensão é .yml ou .yaml e se o arquivo foi enviado para o GitHub. Também confira se o evento escolhido corresponde à branch que recebeu o commit.

O teste precisa de uma senha ou chave

Não coloque a credencial diretamente no YAML. Cadastre-a em Settings > Secrets and variables > Actions e use uma referência como ${{ secrets.NOME_DA_CHAVE }}. A documentação do GitHub recomenda limitar o acesso ao mínimo necessário, e explica que um segredo só fica disponível quando é incluído explicitamente no workflow. Para dúvidas sobre variáveis locais, veja também nosso guia sobre variáveis de ambiente no Node.js.

Também evite imprimir segredos no log. A própria documentação alerta que a ocultação automática não é uma garantia para todas as formas de transformação de um valor sensível.

Quando vale adicionar mais etapas?

Depois que esse fluxo básico estiver estável, você pode acrescentar lint, cobertura de testes, build e análise de segurança. Faça isso aos poucos. Um workflow com dezenas de etapas difíceis de entender vira outro tipo de problema: ninguém sabe qual falha importa e a equipe começa a ignorar o sinal vermelho.

Para projetos que precisam testar várias versões do Node ou mais de um sistema operacional, use uma matrix. Ela cria combinações do mesmo job, mas também aumenta o consumo de minutos e o tempo de feedback. Para um projeto pequeno, testar primeiro a versão oficialmente suportada costuma ser mais sensato do que montar uma matriz cinematográfica.

Perguntas frequentes

O GitHub Actions é gratuito?

O acesso e os limites dependem do tipo de repositório, conta e plano. Workflows também podem consumir minutos e armazenamento conforme o ambiente usado. Consulte os limites atuais da sua conta antes de transformar o Actions em um processo pesado de build.

Preciso instalar o GitHub Actions no computador?

Não. O workflow é armazenado no repositório e executado por um runner. Você só precisa do Git para enviar o arquivo e de um projeto configurado para o comando que deseja automatizar.

Posso rodar o workflow manualmente?

Sim. Acrescente o evento workflow_dispatch: em on. Depois de o arquivo estar na branch padrão, o GitHub exibirá a opção de iniciar a execução pela interface da aba Actions.

Posso usar GitHub Actions com Python ou Java?

Sim. O princípio é o mesmo: preparar o ambiente, instalar dependências e executar os testes. O que muda são a action de configuração e os comandos, como pytest para Python ou ./mvnw test para um projeto Java.

Conclusão

Um workflow pequeno já resolve uma tarefa importante: garantir que cada mudança passe pelo mesmo teste, sem depender da memória de quem fez o commit. Comece com o arquivo acima, confirme uma execução verde e depois adapte o fluxo ao projeto. Automação boa não é a que tem mais YAML; é a que encontra um erro antes do usuário.