Como usar GitHub Actions para executar um script Python automaticamente

Sim, dá para executar um script Python automaticamente sem manter o computador ligado. O caminho mais simples é criar um workflow do GitHub Actions, escolher quando ele deve rodar e informar o comando que inicia o programa.

Neste guia, vamos montar um exemplo que pode ser acionado por um novo push, manualmente pela aba Actions ou em um horário definido. O mesmo modelo serve para testes, relatórios, robôs de coleta e pequenas rotinas de manutenção.

O que é o GitHub Actions?

O GitHub Actions é o sistema de automação integrado aos repositórios do GitHub. Cada automação fica descrita em um arquivo YAML dentro da pasta .github/workflows. Quando um evento acontece, o GitHub cria uma execução e roda as etapas em uma máquina virtual chamada runner.

Na prática, você não precisa configurar um servidor só para instalar dependências e chamar python relatorio.py. O serviço prepara o ambiente, baixa o código e mostra os logs da execução. Ele não transforma um script ruim em um serviço confiável, mas elimina bastante trabalho repetitivo.

Antes de começar

• uma conta no GitHub;
• um repositório com pelo menos um arquivo Python;
• conhecimento básico de terminal e Python;
• dependências registradas em requirements.txt, se o script usar bibliotecas externas.

Se você ainda está organizando o ambiente local, o guia do JSMS sobre como criar um ambiente virtual Python no VS Code ajuda a separar as dependências do projeto.

1. Crie um script Python simples

Para testar a automação, crie na raiz do repositório um arquivo chamado relatorio.py com este conteúdo:

from datetime import datetime, timezone

agora = datetime.now(timezone.utc).astimezone()
print(f"Execução concluída em {agora:%d/%m/%Y às %H:%M:%S}")

O exemplo apenas imprime data e hora. Isso é intencional: primeiro verifique se a engrenagem funciona; depois troque o conteúdo pela sua tarefa real. Um relatório pode salvar um arquivo, chamar uma API, atualizar um banco ou enviar uma notificação, desde que as credenciais não sejam colocadas no código.

2. Crie o workflow

No repositório, crie a pasta .github/workflows e dentro dela salve o arquivo python-automatico.yml. Cole o workflow abaixo:

name: Executar script Python

on:
  workflow_dispatch:
  schedule:
    - cron: '0 11 * * 1-5'

jobs:
  executar:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Baixar código
        uses: actions/checkout@v6

      - name: Configurar Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Executar script
        run: python relatorio.py

O gatilho workflow_dispatch deixa um botão para iniciar a execução manualmente. Já schedule usa a sintaxe cron: neste exemplo, 0 11 * * 1-5 representa 11h UTC de segunda a sexta. Como o horário de Brasília normalmente fica três horas atrás do UTC, isso equivale a 8h em Brasília. Confirme o fuso antes de usar horários críticos.

O GitHub informa que workflows agendados rodam no último commit da branch padrão. A documentação também registra que o intervalo mínimo de agendamento é de cinco minutos. Para tarefas importantes, trate o horário como uma janela, não como garantia de precisão de um relógio.

3. Entenda cada etapa

• runs-on: ubuntu-latest: escolhe um runner Linux hospedado pelo GitHub.
• actions/checkout: baixa os arquivos do repositório para o runner.
• actions/setup-python: prepara a versão de Python informada no campo python-version.
• run: python relatorio.py: executa o programa. Se ele terminar com erro, a etapa aparece como falha.

Para projetos com dependências, acrescente a instalação antes da execução:

      - name: Instalar dependências\n        run: python -m pip install -r requirements.txt\n

O uso de setup-python é recomendado na documentação do GitHub porque fixa o interpretador usado no runner. Ainda assim, fixe versões de bibliotecas no seu projeto quando uma atualização automática puder quebrar o resultado.

4. Como usar chaves de API com segurança

Se o script precisar de uma API, não coloque o token em relatorio.py, no YAML ou em um commit. No repositório, abra Settings > Secrets and variables > Actions, crie um segredo chamado API_TOKEN e passe-o ao processo como variável de ambiente:

      - name: Executar com token
        env:
          API_TOKEN: ${{ secrets.API_TOKEN }}
        run: python relatorio.py

No Python, leia o valor com os.environ["API_TOKEN"]. Evite imprimir a variável nos logs. O GitHub alerta que segredos têm restrições em execuções originadas por forks e em alguns eventos; para autenticação em provedores de nuvem compatíveis, considere OIDC em vez de credenciais duradouras.

5. Faça o primeiro teste

1. Envie o arquivo YAML para a branch padrão.
2. Abra a aba Actions do repositório.
3. Selecione o workflow “Executar script Python”.
4. Clique em Run workflow e escolha a branch.
5. Abra a execução e confira o log da etapa “Executar script”.

Se a opção manual não aparecer, confira se o arquivo está dentro de .github/workflows e se o workflow foi enviado para a branch padrão. Se o erro for “file not found”, confirme o caminho do script. Se faltar uma biblioteca, revise o requirements.txt e a etapa de instalação.

Quando vale a pena usar GitHub Actions?

Ele é uma boa escolha para tarefas pequenas e repetíveis ligadas a um repositório: rodar testes a cada alteração, gerar documentação, produzir um relatório diário ou chamar uma API em horários definidos. Também é útil para quem quer automatizar sem administrar um servidor.

Não é a melhor ferramenta para qualquer cenário. Processos longos, jobs que precisam de armazenamento permanente, sistemas que exigem execução a cada segundo e rotinas com requisitos especiais de rede podem pedir um servidor, um contêiner ou um serviço de filas. O runner é temporário: se o script gerar um arquivo que precisa sobreviver, publique-o em um artefato ou envie-o para um armazenamento externo.

Conclusão

O ponto central é separar três decisões: quando executar, qual ambiente preparar e qual comando chamar. Com um YAML curto, o GitHub Actions resolve o ciclo básico de baixar o código, preparar o Python e rodar o script. A partir daí, o cuidado passa a ser o mesmo de qualquer automação: tratar erros, proteger segredos e verificar se o resultado realmente foi produzido.

Fontes consultadas em 28 de agosto de 2026: guia oficial do GitHub para Python, sintaxe de workflows, uso de secrets e runners hospedados pelo GitHub.