O GitHub Actions permite rodar scripts automaticamente dentro de um repositório, sem que você precise abrir o computador toda vez. Basta criar um arquivo YAML na pasta .github/workflows, escolher o evento que dispara a tarefa e definir os comandos que o runner (a máquina temporária do GitHub) deve executar.
Neste tutorial, vou montar uma automação simples com Python que pode ser iniciada manualmente, executada depois de um push na branch main ou agendada para os dias úteis. O mesmo modelo serve para testes, geração de relatórios, validação de arquivos e pequenas rotinas de manutenção.
O que é o GitHub Actions?
O GitHub Actions é a plataforma de automação do GitHub. Um workflow é um arquivo de configuração que descreve quando e como uma tarefa deve ser executada. Dentro dele ficam um ou mais jobs; cada job reúne steps, como baixar o código, instalar uma dependência e chamar um script.
O job roda em um runner, que é o ambiente de execução fornecido pelo GitHub ou uma máquina própria configurada para isso. Na prática, o computador que executa o código não precisa ser o seu notebook. Os resultados e os logs ficam associados à execução na aba Actions do repositório.
Isso não transforma qualquer script em um serviço permanente. O Actions é ótimo para tarefas disparadas por eventos ou horários, mas não é a escolha adequada para manter um processo web 24 horas ligado. Para esse cenário, você normalmente precisa de um servidor, contêiner ou serviço de hospedagem próprio.
Pré-requisitos
- um repositório no GitHub com o script que será executado;
- permissão para gravar arquivos no repositório;
- um script que funcione localmente e não dependa de caminhos exclusivos do seu computador;
- se houver tokens ou senhas, esses valores devem ser cadastrados como secrets, e não escritos no YAML.
Para o exemplo, crie este arquivo em scripts/relatorio.py:
from datetime import datetime, timezone
agora = datetime.now(timezone.utc).isoformat()
print(f"Relatório executado em {agora}")
Como criar o workflow passo a passo
1. Crie a pasta e o arquivo YAML
Na página do repositório, selecione Add file > Create new file e informe o caminho .github/workflows/relatorio.yml. O GitHub só encontra workflows salvos dentro de .github/workflows; a extensão deve ser .yml ou .yaml.
2. Cole a configuração
Use este workflow mínimo. Ele combina três formas úteis de disparo: manual, por alteração na branch principal e por horário:
name: Executar relatório Python
on:
workflow_dispatch:
push:
branches: [main]
paths:
- 'scripts/**'
schedule:
- cron: '0 12 * * 1-5'
timezone: 'America/Sao_Paulo'
permissions:
contents: read
jobs:
executar:
runs-on: ubuntu-latest
steps:
- name: Baixar o código
uses: actions/checkout@v4
- name: Preparar Python
uses: actions/setup-python@v5
with:
python-version: '3.12'
- name: Rodar o script
run: python scripts/relatorio.py
O bloco on define os gatilhos. workflow_dispatch coloca um botão para iniciar a execução manualmente. O gatilho push reage a alterações na main, mas o filtro paths evita rodar a tarefa quando a mudança aconteceu em outra parte do projeto. Já schedule usa a sintaxe tradicional do cron: neste caso, a rotina está programada para 9h, de segunda a sexta, no horário de Brasília.
O GitHub documenta que os horários agendados usam UTC por padrão e que é possível declarar um fuso IANA, como America/Sao_Paulo. Ainda assim, tarefas críticas não devem depender de uma execução agendada sem monitoramento: atrasos e mudanças no repositório podem exigir uma checagem adicional.
3. Faça o commit
Clique em Commit changes. O commit na branch dispara o workflow por causa do evento push. Depois, abra a aba Actions, escolha “Executar relatório Python” e entre na execução para acompanhar cada step e ler a saída do print.
Para testar o botão manual, abra o workflow, clique em Run workflow, selecione a branch e confirme. Se essa opção não aparecer, confira se o arquivo foi salvo em .github/workflows e se contém workflow_dispatch:.
Como usar secrets sem vazar senhas
Se o script precisar de uma chave de API, abra Settings > Secrets and variables > Actions no repositório e clique em New repository secret. Dê um nome simples, como API_TOKEN, e cole o valor somente no campo protegido.
Depois, passe a variável para o step:
- name: Rodar integração
env:
API_TOKEN: ${{ secrets.API_TOKEN }}
run: python scripts/integracao.py
No Python, leia o valor com os.environ["API_TOKEN"]. Não use print(os.environ["API_TOKEN"]) e não grave o segredo em um arquivo versionado. A documentação do GitHub também alerta que secrets, com exceção do GITHUB_TOKEN, não são enviados ao runner quando o workflow é acionado a partir de um repositório bifurcado. Essa regra é importante para não entregar credenciais a código que você não controla.
Como conferir se a automação funcionou
- Abra a aba Actions e confirme que o workflow aparece na lista.
- Abra a execução mais recente e verifique se todos os steps têm marca verde.
- Expanda “Rodar o script” e confira a mensagem impressa pelo Python.
- Para testar um erro, altere temporariamente o caminho do script e observe o log; depois corrija o YAML.
Uma automação confiável precisa falhar de forma visível. Em vez de esconder erros com comandos que sempre retornam sucesso, faça o script terminar com código diferente de zero quando a tarefa não puder ser concluída. Assim, o GitHub marca o job como falho e você consegue configurar notificações ou uma etapa posterior de tratamento.
Problemas comuns
O workflow não aparece
O motivo mais frequente é o caminho incorreto. Confira se o arquivo está realmente em .github/workflows/, se a extensão é YAML e se o commit foi enviado para o repositório correto.
O horário está diferente
Revise o cron e o campo timezone. Sem um fuso explícito, raciocine em UTC. Também lembre que a execução agendada usa o último commit da branch padrão, não necessariamente a branch em que você estava trabalhando.
O script funciona no PC, mas falha no runner
O runner começa em um ambiente limpo. Dependências precisam ser instaladas no próprio workflow, variáveis devem ser declaradas e caminhos absolutos do seu computador precisam ser removidos. Para projetos reais, acrescente uma etapa de instalação, como pip install -r requirements.txt, antes de chamar o script.
Vale a pena usar o GitHub Actions?
Sim, quando o código já está no GitHub e a tarefa pode ser descrita como uma sequência reproduzível. É uma solução prática para rodar testes a cada alteração, gerar um relatório diário ou validar arquivos sem depender da disciplina de alguém lembrar de executar um comando.
O limite aparece quando a rotina precisa de estado permanente, acesso a dispositivos da rede local ou controle fino de custos e infraestrutura. Nesse caso, GitHub Actions pode continuar como parte do fluxo, mas não deve ser tratado como substituto automático de um servidor. Comece com o workflow manual, confirme os logs e só então ligue o agendamento.
Se você ainda está se acostumando a programar pela nuvem, o guia do JSMS sobre GitHub Codespaces mostra outra peça desse ecossistema: escrever e executar código no navegador. Codespaces e Actions resolvem problemas diferentes, mas podem trabalhar juntos no mesmo projeto.
Perguntas frequentes
Preciso deixar meu computador ligado?
Não para um workflow executado em um runner hospedado pelo GitHub. O job acontece no ambiente de execução configurado no arquivo YAML.
Posso executar o workflow somente em determinados arquivos?
Sim. Filtros como paths no evento push permitem limitar a execução a diretórios ou padrões específicos.
Onde vejo o resultado do script?
Na aba Actions, dentro da execução do workflow. Os logs ficam separados por job e step.
É seguro colocar uma chave de API no YAML?
Não. Cadastre a chave como secret e injete-a no step por variável de ambiente. Também evite imprimir o valor nos logs.
Fontes consultadas em 27 de agosto de 2026: Quickstart do GitHub Actions, sintaxe de workflows, guia de secrets e documentação geral do Actions.