Como usar o GitHub Actions para automatizar tarefas de programação

O GitHub Actions permite automatizar testes, verificações e tarefas de manutenção diretamente no repositório. Para começar, você cria um arquivo YAML dentro de .github/workflows, escolhe o evento que dispara a rotina e define os comandos que serão executados.

Na prática, isso significa que um projeto pode rodar testes a cada push, conferir um pull request ou executar uma tarefa em horário programado sem depender do seu computador ligado. É uma forma simples de tirar tarefas repetitivas da cabeça — e também de descobrir um erro antes de ele chegar ao usuário.

O que é o GitHub Actions?

O GitHub Actions é a plataforma de integração e entrega contínuas — CI/CD — do GitHub. Em linguagem simples, ele observa acontecimentos no repositório e inicia uma sequência de tarefas. Essas tarefas podem compilar um programa, rodar testes, gerar um pacote, publicar uma documentação ou iniciar um processo de implantação.

A estrutura tem quatro peças principais:

• Workflow: o arquivo YAML que descreve a automação.
• Evento: o acontecimento que inicia a execução, como push, pull_request, um horário ou um acionamento manual.
• Job: um conjunto de etapas executado em um mesmo ambiente.
• Step: um comando de terminal ou uma action reutilizável.

O GitHub informa que os workflows ficam no diretório .github/workflows e podem usar máquinas virtuais hospedadas pela própria plataforma, com Linux, Windows ou macOS. Também é possível configurar um runner próprio, mas isso adiciona manutenção e responsabilidade de segurança.

Como criar um workflow básico

O caminho mais fácil é começar com uma verificação pequena. Neste exemplo, o GitHub Actions baixa o código, instala o Python e verifica se os arquivos Python do projeto podem ser compilados:

name: Verificar projeto Python

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

permissions:
  contents: read

jobs:
  verificar:
    runs-on: ubuntu-latest

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

      - name: Preparar o Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Verificar sintaxe
        run: python -m compileall -q .

Passo a passo

1. Abra um repositório no GitHub ou use um projeto que já exista.
2. Crie a pasta .github/workflows na raiz do projeto.
3. Salve o conteúdo acima como verificar.yml dentro dessa pasta.
4. Troque main pelo nome da sua branch principal, se necessário.
5. Faça commit e envie o arquivo para o GitHub.
6. Abra a aba Actions do repositório e confira a execução.

O arquivo pode ter qualquer nome terminado em .yml ou .yaml. O nome exibido na aba Actions vem de name; por isso, vale usar um texto que explique a finalidade da rotina.

Como testar manualmente

O evento workflow_dispatch adiciona a opção de execução manual. Depois que o arquivo estiver na branch padrão, entre em Actions, escolha o workflow na coluna lateral e clique em Run workflow. Essa opção é útil para tarefas que não devem rodar a cada alteração, como gerar um relatório, limpar artefatos ou publicar uma versão.

Também dá para combinar a execução manual com eventos automáticos. No exemplo, o workflow roda quando há um push na branch main, em pull requests e quando alguém o inicia pela interface. O mesmo arquivo, portanto, cobre o fluxo normal e um teste sob demanda.

Como agendar uma tarefa automática

Para rodar a rotina em horários definidos, use o evento schedule com a sintaxe POSIX cron. Este exemplo executa o job todos os dias às 9h no horário de Brasília:

on:
  schedule:
    - cron: "0 12 * * *"
      timezone: "America/Sao_Paulo"
  workflow_dispatch:

O GitHub documenta que o intervalo mínimo de uma tarefa agendada é de cinco minutos. Sem um fuso declarado, o agendamento usa UTC; por isso, informar America/Sao_Paulo evita a conta mental e deixa o arquivo mais claro. O horário também precisa ser pensado com cuidado: uma tarefa frequente pode consumir minutos de execução e gerar ruído desnecessário.

Onde entram as actions e os comandos?

O campo run executa comandos no ambiente do job. Já o campo uses chama uma action pronta, como as usadas para baixar o código ou configurar uma linguagem. Actions economizam tempo, mas não são mágicas: uma action de terceiros recebe o contexto permitido pelo workflow e deve ser escolhida e atualizada com critério.

Para quem está começando, a regra é separar responsabilidades. Use uma etapa para preparar o ambiente, outra para instalar dependências e outra para testar. Se uma etapa falhar, o log mostra onde a execução parou. Em projetos maiores, jobs independentes também podem rodar em paralelo ou depender uns dos outros com needs.

Se você ainda está organizando o trabalho do repositório, o guia do JSMS sobre GitHub Projects ajuda a separar tarefas e acompanhar o que deve entrar no próximo ciclo.

Como guardar senhas e tokens

Não coloque senhas diretamente no arquivo YAML. Cadastre valores sensíveis em Settings > Secrets and variables > Actions e use a expressão secrets.NOME_DO_SEGREDO no workflow. O exemplo abaixo mostra a forma correta de passar um token para um comando:

- name: Chamar serviço externo
  env:
    API_TOKEN: ${{ secrets.API_TOKEN }}
  run: python scripts/enviar.py

O token continua fora do código, mas isso não transforma qualquer workflow em seguro. Evite imprimir variáveis no log, limite as permissões do GITHUB_TOKEN e desconfie de scripts que montam comandos com texto vindo de pull requests. Em repositórios públicos, execuções originadas de forks têm regras próprias e não recebem secrets comuns automaticamente.

Erros comuns e como corrigir

• O workflow não aparece: confira se o arquivo está em .github/workflows, se a extensão é YAML e se o commit chegou ao GitHub.
• O botão de execução manual não aparece: verifique se workflow_dispatch está no arquivo da branch padrão.
• O job falha no primeiro comando: abra os logs e confira o sistema operacional, o diretório atual e as dependências instaladas.
• A rotina roda mais vezes do que o esperado: revise os eventos e as branches em on. Um push sem filtro pode disparar o job em qualquer branch.
• O segredo aparece no terminal: remova comandos de diagnóstico que imprimem o ambiente e substitua o token imediatamente.

Vale a pena usar o GitHub Actions?

Para um projeto hospedado no GitHub, geralmente vale a pena quando existe uma tarefa repetitiva que precisa ser executada sempre do mesmo jeito. Um teste automático simples já evita depender da memória do desenvolvedor. A ferramenta também faz sentido para bibliotecas, APIs, sites estáticos e projetos pessoais que precisam gerar versões ou verificar qualidade.

Ela não resolve tudo sozinha. Workflows mal configurados podem gastar execução, quebrar por causa de uma action desatualizada ou dar uma falsa sensação de segurança. Comece com um job curto, registre as permissões necessárias e só depois acrescente publicação, deploy e integrações externas.

Perguntas frequentes

O GitHub Actions é um programa instalado no computador?

Não. O workflow é armazenado no repositório e executado por um runner hospedado pelo GitHub ou por uma máquina que você configurar.

Posso executar um workflow sem fazer um novo commit?

Sim. Inclua workflow_dispatch e use a opção Run workflow na aba Actions, desde que o arquivo esteja disponível na branch padrão.

Preciso usar Docker para começar?

Não. Um workflow pode executar comandos diretamente no runner. Docker é uma opção para cenários que precisam de ambientes ou serviços isolados.

Onde vejo por que a automação falhou?

Na aba Actions, abra a execução e depois o job com erro. Cada step tem um log separado, o que ajuda a localizar o comando que falhou.