O que é e como usar Cron Jobs com GitHub

Se você já precisou rodar um script automaticamente em um horário programado — como todo dia à meia-noite ou a cada hora — você está procurando por um cron job.

Mas você sabia que pode rodar cron jobs diretamente no GitHub, sem precisar de servidores ou infraestrutura?

Aqui vai um guia simples e moderno para cron jobs usando GitHub Actions.

O que é um Cron Job?

Um cron job nada mais é do que um agendador de tarefas baseado em tempo. Ele diz ao seu sistema:

“Execute este script às X horas, a cada Y intervalo.”

Tradicionalmente, você configuraria isso em um servidor Linux usando o comando crontab. Mas em 2025, podemos fazer melhor: automação serverless diretamente no GitHub.

🧠 Guia Rápido da Sintaxe Cron

Quando você define:

schedule:
-   cron: '0 0 * * *'

Você está dizendo ao GitHub Actions:

“Execute este job às 00:00 UTC todos os dias.”

As expressões cron seguem este formato:

┌───────────── minuto (0 - 59)
│ ┌───────────── hora (0 - 23)
│ │ ┌───────────── dia do mês (1 - 31)
│ │ │ ┌───────────── mês (1 - 12)
│ │ │ │ ┌───────────── dia da semana (0 - 6) (Domingo = 0)
│ │ │ │ │
│ │ │ │ │
* * * * *

✅ Exemplos Úteis

⚙️ Por Que Usar Cron Jobs no GitHub?

Você obtém:

• ✅ Computação gratuita (via GitHub Actions)

• ✅ Sem infraestrutura para gerenciar

• ✅ Acesso nativo aos seus repositórios, issues, APIs, etc.

• ✅ Logs, versionamento e lógica acionada por Pull Requests

Perfeito para:

• Executar scripts de limpeza

• Sincronizar dados com APIs

• Enviar relatórios ou resumos

• Manter dependências atualizadas

🧪 Exemplos de Casos de Uso Reais

• ✅ Buscar e armazenar dados de uma API diariamente

• ✅ Fechar issues obsoletos no GitHub toda semana

• ✅ Fazer ping em um endpoint para manter um servidor ativo

• ✅ Postar uma mensagem no Slack toda segunda-feira

Você pode até integrar secrets, buscar conteúdo remoto e acionar workflows de forma condicional.

🛠 Como Configurar um Cron Job no GitHub (Passo a Passo)

1. Crie um arquivo .github/workflows/cron.yml no seu repositório:

name: Executar Tarefa Agendada

on:
  schedule:
    - cron: '0 0 * * *' # todo dia à meia-noite UTC
  workflow_dispatch: # opcional: permite acionar manualmente

jobs:
  run-script:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - name: Executar Meu Script
        run: node ./scripts/meu-script.js

🧠 Dica: Use crontab.guru para criar sua expressão cron.

2. Faça commit e push. O GitHub agora executará essa tarefa ou job automaticamente no cronograma estipulado.

⚠️ Cron Jobs no GitHub Não São Executados no Tempo Exato

Algo que muitos desenvolvedores não percebem: o GitHub Actions não garante execução exata no horário para workflows agendados.

Quando você agenda um job para 0 0 * * * (meia-noite UTC), o GitHub pode não executá-lo exatamente à meia-noite. Pode haver um atraso de alguns minutos, às vezes até mais, dependendo da quantidade de jobs agendados no momento.

Isso acontece porque:

• O GitHub enfileira milhares de workflows baseados em cron em todos os repositórios públicos e privados.

• Não há SLA (acordo de nível de serviço) para precisão no horário.

🛠 Soluções e Alternativas

Use GitHub Enterprise / Runners Premium

Com runners hospedados no GitHub em planos pagos, especialmente runners self-hosted ou enterprise, você pode ter:

• Tempos de fila reduzidos

• Agendamento mais previsível

• Limites de concorrência maiores

Ainda assim, nem mesmo o GitHub Enterprise garante precisão de segundos.

Use Serviços Externos de Agendamento

Se precisão no horário é crítica (ex.: você precisa acessar uma API exatamente às 03:00 UTC), considere usar:

• cron-job.org — Gratuito, simples, cron como serviço

• AWS EventBridge Scheduler — Nativo na nuvem, escalável, preciso

• Zapier / n8n / Make — Ótimos para automação de APIs sem código

• Cloudflare Workers + Cron Triggers — Rápido, serverless, altamente confiável

Esses serviços podem acessar seu endpoint ou acionar um workflow_dispatch do GitHub, oferecendo mais controle.

Para operações sensíveis ao tempo ou coordenadas em nível global, considere agendadores externos ou um modelo híbrido (ex.: acionamento externo → GitHub Action via API).

🧰 Bônus: Debug + Boas Práticas

• Sempre adicione workflow_dispatch para poder testar manualmente

• Use actions/setup-node se seu script precisar de Node/npm

• Utilize cron jobs no GitHub quando a precisão no horário não for crítica, como:

  • Tarefas de limpeza diária

  • Relatórios semanais

  • Sincronização com APIs com margem de tempo

Considerações Finais

GitHub Actions + cron é como ter cron como serviço — uma ferramenta poderosa e gratuita de automação que vive ao lado do seu código. Você não precisa subir servidores ou criar funções na nuvem. Basta fazer commit e deixar rodar. Até a próxima!