Como usar GitHub Actions para automatizar tarefas no seu projeto

GitHub Actions permite automatizar testes, verificações e outras tarefas diretamente dentro de um repositório. Para começar, basta criar um arquivo YAML na pasta .github/workflows/, escolher o evento que dispara o processo e listar os comandos que devem ser executados.

Na prática, isso transforma uma rotina manual — como instalar dependências e rodar testes toda vez que alguém envia código — em uma sequência repetível. O exemplo abaixo usa um projeto Node.js, mas a mesma lógica serve para Python, PHP, Java, aplicativos mobile e scripts de manutenção.

O que é o GitHub Actions?

GitHub Actions é o sistema de automação do GitHub. Ele executa workflows, que são arquivos de configuração escritos em YAML. Um workflow pode ser iniciado por um push, por uma solicitação de alteração (pull request), por horário programado ou manualmente.

Cada workflow contém um ou mais jobs. Um job é um conjunto de etapas executado em uma máquina chamada runner. Dentro dele, você pode chamar ações prontas, como baixar o código do repositório, configurar uma versão do Node.js ou rodar um comando do projeto.

Essa separação parece burocrática no começo, mas ajuda a entender o processo: o evento decide quando executar, o job define onde executar e os passos determinam o que fazer.

Antes de criar o primeiro workflow

• Tenha um repositório no GitHub com o código do projeto.
• Saiba qual comando instala as dependências e qual comando executa os testes.
• Confirme a versão da linguagem usada pelo projeto.
• Se houver tokens ou senhas, guarde-os como secrets, não no arquivo YAML.

O arquivo do workflow precisa estar no branch padrão para que os eventos agendados funcionem como esperado. A documentação do GitHub também recomenda limitar permissões quando o job não precisa escrever no repositório.

Como criar um workflow de testes para Node.js

No repositório, crie o arquivo .github/workflows/testes.yml. O caminho é importante: qualquer arquivo YAML nessa pasta pode ser interpretado como um workflow.

Para um projeto Node.js que possui package-lock.json e o script test no package.json, use este exemplo:

name: Testes do projeto

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

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest

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

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

      - name: Instalar dependências
        run: npm ci

      - name: Executar testes
        run: npm test

Salve o arquivo, faça o commit e envie para o GitHub. Depois, abra a aba Actions do repositório. O workflow deverá aparecer ali; um push no branch main ou uma alteração direcionada a ele inicia uma execução.

O exemplo assume que o projeto realmente usa npm, tem um arquivo de lock e possui um script chamado test. Se o projeto usa Yarn, pnpm ou outro comando, troque as etapas sem copiar o exemplo como se fosse universal.

Como executar a automação manualmente

A linha workflow_dispatch: adiciona um botão para iniciar o workflow pela interface do GitHub. Isso é útil para repetir testes, gerar um pacote ou executar uma tarefa de manutenção sem criar um commit artificial.

Para usar a execução manual, abra Actions, escolha o workflow na coluna lateral e selecione Run workflow. Se o botão não aparecer, verifique se o arquivo está no branch padrão e se o evento foi escrito corretamente.

Como programar uma tarefa com cron

Também é possível executar um workflow em horários definidos. O GitHub usa a sintaxe POSIX do cron e, por padrão, interpreta o horário em UTC. Este trecho roda de segunda a sexta às 12h30 UTC:

on:
  schedule:
    - cron: '30 12 * * 1-5'

Não use o agendamento para tarefas que exigem precisão de segundos. A própria documentação alerta que execuções podem atrasar em períodos de alta carga, especialmente no começo de cada hora; em situações extremas, trabalhos enfileirados podem ser descartados. Escolher um minuto fora de :00 reduz a chance de disputa.

Como usar secrets sem expor tokens

Para adicionar uma credencial, abra Settings > Secrets and variables > Actions no repositório e crie um secret, por exemplo API_TOKEN. No YAML, faça referência a ele pelo contexto secrets:

jobs:
  consulta:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Consultar serviço externo
        env:
          API_TOKEN: ${{ secrets.API_TOKEN }}
        run: node scripts/consulta-api.js

O script deve ler a variável de ambiente e nunca imprimi-la no log. Não coloque o valor do token no código, no README, em parâmetros visíveis ou em mensagens de erro. Secrets também exigem cuidado em workflows acionados por contribuições externas, porque o código executado precisa ser tratado como potencialmente não confiável.

Esse cuidado combina com a regra básica de qualquer automação: dê ao job apenas as permissões de que ele precisa. Para aprofundar o assunto, veja também o nosso guia sobre como proteger chaves de API no n8n sem expor seus segredos.

Como conferir se o workflow funcionou

Depois de enviar o arquivo, abra a execução na aba Actions e observe cada job e cada step. Um passo verde indica sucesso; um passo vermelho mostra onde o processo parou. Clique no passo com erro para ler o log.

Os problemas mais comuns são simples:

• O workflow não aparece: confira a extensão .yml ou .yaml e o caminho .github/workflows/.
• npm ci falha: veja se o package-lock.json está versionado e compatível com o package.json.
• O teste não é encontrado: confira o campo scripts.test no package.json ou troque o comando pelo teste real do projeto.
• A variável está vazia: confirme o nome do secret, o repositório e o escopo do ambiente.
• A execução fica lenta: revise dependências, use cache quando houver suporte e evite instalar ferramentas desnecessárias.

Quando vale a pena usar GitHub Actions?

Ele faz sentido quando a tarefa se repete e precisa deixar um registro verificável. Testes a cada alteração, análise de qualidade, geração de documentação, publicação de um site estático e criação de pacotes são bons pontos de partida.

Não é obrigatório automatizar tudo de uma vez. Comece com um workflow que apenas instala dependências e testa o código. Quando ele estiver confiável, adicione validações, artefatos ou deploy. Um arquivo enorme que tenta fazer o trabalho de cinco sistemas costuma ser mais difícil de proteger e depurar do que uma sequência de workflows menores.

Perguntas frequentes

Preciso instalar um servidor para usar GitHub Actions?

Não para o caso básico. O workflow pode usar um runner hospedado pelo GitHub. Projetos com exigências específicas de rede, hardware ou ambiente podem precisar de um runner próprio.

GitHub Actions funciona apenas com JavaScript?

Não. O runner executa comandos do sistema e pode ser configurado para diferentes linguagens. O exemplo usa Node.js apenas para mostrar um caminho curto e fácil de testar.

Posso iniciar um workflow sem fazer commit?

Sim, desde que o arquivo tenha o evento workflow_dispatch. Nesse caso, a execução manual pode ser iniciada pela aba Actions do repositório.

O cron do GitHub Actions usa o horário de Brasília?

Por padrão, não. O cron usa UTC. Converta o horário desejado e lembre que o agendamento pode sofrer atraso em períodos de alta carga.