Expressões cron explicadas: como ler e escrever agendamentos cron

Se você já implantou uma aplicação web, configurou um pipeline de CI/CD ou gerenciou um servidor Linux, você quase certamente já encontrou uma expressão cron. Cinco asteriscos encarando você a partir de um arquivo de configuração. Uma string enigmática como 0 2 * * 0 enterrada em um workflow do GitHub Actions. Um agendamento do AWS EventBridge que ninguém na equipe entende mais por completo. As expressões cron estão em toda parte — e elas são genuinamente confusas se você não tirou um tempo para aprender o sistema por trás delas.

Este guia é a referência que você deveria adicionar aos favoritos. Ele cobre tudo, desde a história do cron e onde ele aparece na infraestrutura moderna, até cada caractere especial, 10 exemplos reais comentados, erros comuns e uma tabela de referência completa. Ao final, você será capaz de ler qualquer expressão cron rapidamente e escrever novas com confiança.

O que é o cron?

O cron é um agendador de tarefas baseado em Unix que executa comandos ou scripts automaticamente em horários e intervalos especificados. O nome vem de Chronos, a personificação grega do tempo — uma escolha apropriada para uma ferramenta cujo propósito inteiro é a automação baseada em tempo. O cron original foi introduzido no Unix Versão 7 em 1979, escrito por Ken Thompson na Bell Labs, e tem sido um pilar dos sistemas operacionais do tipo Unix desde então.

O agendador funciona lendo arquivos de configuração chamados crontabs (tabelas de cron) — arquivos de texto simples em que cada linha define uma tarefa agendada. Um processo daemon em segundo plano (crond) acorda a cada minuto, verifica todos os crontabs ativos e executa quaisquer tarefas cujo agendamento corresponda ao horário atual. É um design lindamente simples que permaneceu fundamentalmente inalterado por mais de quatro décadas.

Onde você encontra o cron hoje

O cron não é apenas uma relíquia do passado Unix. A sintaxe de expressão cron é o padrão de fato para expressar agendamentos recorrentes em toda a stack de software moderna:

• crontab do Linux e do macOS: O caso de uso original. Execute crontab -e em qualquer máquina Linux ou macOS para editar seu agendamento cron pessoal.
• GitHub Actions: Os arquivos de workflow usam a sintaxe cron sob o gatilho schedule:para executar pipelines de CI/CD de forma recorrente.
• AWS EventBridge (antigo CloudWatch Events): Aciona funções Lambda, tarefas ECS e outros serviços da AWS em um agendamento usando uma variante cron de 6 campos.
• CronJobs do Kubernetes: O recurso CronJob executa cargas de trabalho em lote dentro de um cluster em um agendamento cron.
• Pipelines de CI/CD: GitLab CI, CircleCI, Jenkins e Bitbucket Pipelines, todos suportam execuções agendadas usando expressões cron.
• Vercel e Netlify: Ambas as plataformas suportam funções serverless acionadas por cron para tarefas como invalidação de cache, busca de dados e builds noturnos.
• Manutenção de banco de dados: A extensão pg_cron do PostgreSQL, o Event Scheduler do MySQL e os serviços de banco de dados gerenciados usam a sintaxe cron para tarefas de vacuum, indexação e backup.
• Agendadores em nível de aplicação: Bibliotecas como node-cron, APScheduler (Python), Quartz (Java) e Sidekiq (Ruby), todas usam expressões cron para definir tarefas recorrentes em segundo plano.

Em resumo: se você trabalha em qualquer área de desenvolvimento de software ou administração de sistemas, as expressões cron são algo que você encontrará regularmente. Aprendê-las uma vez gera dividendos em toda parte.

A estrutura de cinco campos

Uma expressão cron padrão consiste em exatamente cinco campos separados por espaços, cada um representando uma unidade de tempo. Juntos, eles definem quando uma tarefa deve ser executada. Aqui está a representação visual canônica:

┌───────────── minute (0–59)
│ ┌─────────── hour (0–23)
│ │ ┌───────── day of month (1–31)
│ │ │ ┌─────── month (1–12)
│ │ │ │ ┌───── day of week (0–7)
│ │ │ │ │
* * * * *

Lendo da esquerda para a direita: minuto, hora, dia do mês, mês, dia da semana. Um asterisco (*) em qualquer campo significa "todo valor possível para este campo". Então * * * * * significa "a cada minuto de cada hora de cada dia" — o agendamento mais permissivo possível.

Campo 1: Minuto (0–59)

O campo de minuto controla em qual(is) minuto(s) dentro de uma hora uma tarefa dispara. Um valor de 0 significa na virada da hora, 30 significa na meia hora e * significa a cada minuto. Este é o campo mais granular do cron padrão — a menor unidade de agendamento é um minuto.

Campo 2: Hora (0–23)

O campo de hora usa o formato de 24 horas. 0 é meia-noite, 9 é 9h, 17 é 17h e 23 é 23h. Não há AM/PM — tudo está no formato de 24 horas. Lembre-se de que o cron sempre roda no fuso horário do servidor, a menos que configurado explicitamente de outra forma.

Campo 3: Dia do mês (1–31)

Controla em qual(is) dia(s) do mês uma tarefa é executada. 1 é o dia primeiro, 15 é o dia quinze, 31 é o dia trinta e um. Cuidado com valores como 31 — em meses com menos dias (fevereiro, abril, junho, etc.), uma tarefa agendada para o dia 31 simplesmente não será executada naquele mês. Algumas implementações suportam o caractere especial L para significar "último dia do mês" independentemente de quantos dias o mês tenha.

Campo 4: Mês (1–12)

O campo de mês usa valores numéricos (1 para janeiro até 12 para dezembro) ou abreviações de três letras (JAN, FEB, MAR, APR, MAY, JUN,JUL, AUG, SEP, OCT, NOV, DEC) na maioria das implementações. Um asterisco significa "todo mês".

Campo 5: Dia da semana (0–7)

Este campo especifica em qual(is) dia(s) da semana a tarefa deve ser executada. A numeração aqui é uma fonte comum de confusão: tanto 0 quanto 7 representam domingo na maioria das implementações de cron (uma peculiaridade herdada do design Unix original). Segunda-feira é 1, terça-feira é 2 e sábado é 6. As abreviações de três letras (SUN, MON, TUE, WED, THU, FRI,SAT) são suportadas na maioria das ferramentas de cron modernas.

Caracteres especiais

O verdadeiro poder das expressões cron vem de seis caracteres especiais que permitem expressar agendamentos complexos de forma concisa. Entendê-los é a chave para a fluência.

* — Curinga (todo valor)

Um asterisco significa "corresponder a todo valor possível neste campo". No campo de minuto, * significa a cada minuto (0 a 59). No campo de mês, significa todo mês. É o valor padrão de "não me importo com este campo".

* * * * *    # Runs every single minute, all day, every day

, — Lista (múltiplos valores)

Uma vírgula separa uma lista de valores específicos. O campo corresponde se o horário atual coincidir com qualquer valor da lista. É assim que você agenda uma tarefa para ser executada em vários horários discretos sem usar um intervalo.

0 9,13,17 * * *    # Runs at 9:00 AM, 1:00 PM, and 5:00 PM every day
0 0 1,15 * *       # Runs at midnight on the 1st and 15th of every month

- — Intervalo (de até)

Um hífen define um intervalo inclusivo de valores. O campo corresponde a todo valor entre o início e o fim, inclusive. É ideal para expressar coisas como "durante o horário comercial" ou "nos dias úteis".

0 9-17 * * *      # Runs at the top of every hour from 9 AM through 5 PM
0 0 * * 1-5       # Runs at midnight every Monday through Friday

/ — Passo (a cada N unidades)

Uma barra define um valor de passo. */5 significa "a cada 5 unidades a partir do mínimo". Você também pode combiná-lo com um intervalo: 0-30/10 significa "a cada 10 unidades entre 0 e 30" (ou seja, 0, 10, 20, 30). Os passos são um dos caracteres especiais mais usados.

*/5 * * * *       # Every 5 minutes (0, 5, 10, 15, ... 55)
*/15 * * * *      # Every 15 minutes (0, 15, 30, 45)
0 */6 * * *       # Every 6 hours (0:00, 6:00, 12:00, 18:00)
0/15 * * * *      # Same as */15 — starts from 0, every 15 minutes

L — Último (apenas algumas implementações)

O caractere L é suportado em algumas implementações de cron (notavelmente o Quartz Scheduler em Java e algumas variantes de cron do Linux) para significar "último". No campo de dia do mês, L significa o último dia do mês atual — seja ele o dia 28, 29, 30 ou 31. Ele resolve o problema de agendar tarefas de "fim de mês" sem saber a duração do mês de antemão.

0 0 L * *         # Midnight on the last day of every month (Quartz/some crons)

? — Nenhum valor específico (cron do Quartz/Java)

O ponto de interrogação é usado no Quartz Scheduler (Java) e em algumas outras ferramentas quando você quer especificar um dia da semana sem também especificar um dia do mês, ou vice-versa. Como não faz sentido lógico especificar ambos (digamos "o dia 15 E uma quarta-feira"), um deles deve ser definido como ? para indicar "não me importo". O cron Unix padrão não usa esse caractere — você usa * em vez disso.

0 9 15 * ?        # Quartz: 9 AM on the 15th, day-of-week unspecified
0 9 ? * MON       # Quartz: 9 AM every Monday, day-of-month unspecified

10 exemplos reais de cron

A melhor forma de consolidar seu entendimento é estudar exemplos reais com o contexto de por que cada agendamento foi escolhido. Aqui estão dez padrões que você encontrará (e usará) regularmente.

1. Todo dia útil às 9h

0 9 * * 1-5

O minuto é 0 (virada da hora), a hora é 9 (9h), o dia do mês e o mês são curingas, e o dia da semana é 1-5 (de segunda a sexta-feira). Usado para lembretes de daily standup, e-mails de relatório enviados no início do dia comercial e tarefas de sincronização matinal de dados que não devem rodar no fim de semana.

2. A cada 15 minutos

*/15 * * * *

A sintaxe de passo */15 no campo de minuto dá a você execuções nos minutos 0, 15, 30 e 45 após cada hora, o dia inteiro. Comum para pings de health check, aquecimento de cache, novas tentativas de webhook e qualquer tarefa de polling quase em tempo real em que você precisa de atualização, mas o tempo real de fato é exagerado ou não está disponível.

3. Todo dia à meia-noite

0 0 * * *

Minuto 0, hora 0, todo o resto curinga. Este é um dos padrões de cron mais comuns que existem. Usado para geração de relatórios diários, rotação de logs, arquivamento de banco de dados, limpeza de arquivos temporários, envio de e-mails de resumo diário e qualquer tarefa "uma vez por dia" que deva rodar fora do horário comercial.

4. Primeiro dia de cada mês à meia-noite

0 0 1 * *

O dia do mês é 1, todo o resto é curinga (exceto o minuto/hora fixos). Isso roda no dia 1º de janeiro, 1º de fevereiro, 1º de março, e assim por diante. O agendamento padrão para geração de faturas mensais, gatilhos de ciclo de cobrança, renovações de assinaturas SaaS e consolidações mensais de análise de dados.

5. Todo domingo às 2h

0 2 * * 0

O dia da semana 0 é domingo, e a hora 2 é 2h — um horário em que o tráfego costuma estar no nível mais baixo. Usado para backups completos semanais do banco de dados, regeneração de sitemap, reindexação de conteúdo para busca e tarefas pesadas de processamento em lote que impactariam o desempenho durante a semana.

6. Dias úteis às 8h30, 12h30 e 17h30

30 8,12,17 * * 1-5

Isso combina uma lista no campo de hora com um intervalo no campo de dia da semana. O minuto 30significa que dispara na marca da meia hora. Usado para lotes de notificações agendadas (notificações push, resumos por e-mail), tarefas de sincronização de dados três vezes ao dia e qualquer fluxo de trabalho em que você queira pontos de contato regulares ao longo do dia comercial sem martelar a cada hora.

7. 1º de janeiro à meia-noite

0 0 1 1 *

O dia do mês 1 e o mês 1 (janeiro) juntos fixam isto no Dia de Ano Novo. Usado para tarefas anuais como renovações de assinaturas anuais, arquivamento dos dados do ano anterior, geração de relatórios anuais de conformidade e redefinição de cotas ou contadores anuais em aplicações.

8. A cada 5 minutos durante o horário comercial nos dias úteis

*/5 9-17 * * 1-5

Uma expressão composta combinando um passo (*/5), um intervalo nas horas (9-17) e um intervalo no dia da semana (1-5). Isso dá a você monitoramento ou polling agressivo — a cada 5 minutos das 9h às 17h, de segunda a sexta-feira — ficando em silêncio durante a noite e nos fins de semana para economizar recursos e evitar fadiga de alertas.

9. A cada 6 horas

0 */6 * * *

O passo no campo de hora (*/6) dá quatro execuções uniformemente espaçadas por dia: meia-noite, 6h, meio-dia e 18h. Usado para sincronização de dados entre sistemas, atualização de tokens de API de longa duração ou credenciais OAuth antes que expirem, e invalidação periódica de cache para conteúdo que muda algumas vezes ao dia, mas não precisa de atualização em nível de minuto.

10. Dia 15 e último dia de cada mês

0 0 15,L * *

Uma lista com vírgula no campo de dia do mês combinando uma data fixa (15) e a forma abreviada do último dia (L). Este é o clássico agendamento de folha de pagamento quinzenal — períodos de pagamento que terminam no dia 15 e no último dia do mês. Observe que L exige uma implementação que o suporte (Quartz, alguns crons do Linux); o crontab padrão não suporta L.

Erros comuns e armadilhas

As expressões cron têm várias armadilhas bem conhecidas que causam incidentes em produção. Entendê-las de antemão vai poupar você de uma dolorosa sessão de depuração às 2 da manhã.

A numeração do dia da semana não é universal

A maioria das implementações de cron Unix trata tanto 0 quanto 7 como domingo. Mas algumas ferramentas (incluindo certas bibliotecas em nível de aplicação) começam a semana na segunda-feira, fazendo 1 = segunda-feira e 7 = domingo. Sempre verifique a convenção de numeração da ferramenta específica que você está usando e prefira usar abreviações de três letras (MON, TUE, etc.) quando a implementação as suportar, para eliminar a ambiguidade.

O cron roda no fuso horário do servidor

Esta é provavelmente a fonte mais comum de bugs de cron em produção. 0 9 * * * significa 9h no fuso horário da máquina que executa a tarefa — que pode ser UTC, US/Eastern ou qualquer outro. Sempre documente a suposição de fuso horário em um comentário ao lado da expressão cron. Para agendadores baseados na nuvem, configure explicitamente o fuso horário se a plataforma o suportar.

# Good practice: always document the timezone
# Runs at 9 AM US/Eastern (UTC-5 or UTC-4 during DST)
0 14 * * 1-5   # 9 AM ET expressed in UTC

O cron do GitHub Actions sempre roda em UTC

O GitHub Actions usa a sintaxe cron padrão de 5 campos sob a chave on: schedule:, mas o agendador sempre opera em UTC — não há opção de configuração de fuso horário. Se você quer que uma tarefa rode às 9h no horário do leste, precisa agendá-la para 0 14 * * * (UTC). Observe também que os workflows agendados do GitHub Actions podem rodar com até 15 minutos de atraso em períodos de alta demanda.

A sintaxe de passo se aplica ao seu campo, não a minutos

Uma leitura equivocada comum: */5 no campo de hora significa a cada 5 horas — não a cada 5 minutos. O passo sempre se aplica à unidade do campo em que está. */5 no campo de minuto é a cada 5 minutos; no campo de hora, a cada 5 horas; no campo de mês, a cada 5 meses.

Tarefas que rodam por mais tempo que seu intervalo podem se sobrepor

O cron é um agendador do tipo dispare e esqueça. Se você agendar uma tarefa a cada 5 minutos e uma instância da tarefa levar 7 minutos para concluir, uma segunda instância começará enquanto a primeira ainda estiver rodando. Isso pode causar condições de corrida, processamento duplicado e corrupção de dados. Use um lock de arquivo ou um advisory lock no seu banco de dados para evitar a execução simultânea da mesma tarefa.

Campos ausentes vs. curingas nem sempre são equivalentes

Em algumas implementações estendidas de cron (particularmente o Quartz), omitir um campo e usar *são tratados de forma diferente. Sempre use todos os campos obrigatórios explicitamente e nunca confie em padrões para agendamentos críticos de produção.

Extensões não padronizadas: cron de 6 campos

O cron Unix padrão tem cinco campos, com o minuto como a granularidade mais fina. Vários sistemas estendem isso com campos adicionais:

Campo de segundos (antes dos demais)

Muitos agendadores em nível de aplicação (node-cron, Quartz, Spring Scheduler) adicionam um campo de segundos no início, dando a você 6 campos. Isso permite agendamento abaixo do minuto, até o segundo. Os campos são: second minute hour day-of-month month day-of-week.

# 6-field cron with seconds prepended (Quartz / node-cron)
0 */5 * * * *    # Every 5 minutes (second=0, minute=*/5, ...)
30 0 9 * * 1-5   # Weekdays at 9:00:30 AM

AWS EventBridge (6 campos com ano)

O AWS EventBridge usa um formato de 6 campos em que um campo de ano é acrescentado ao final:minute hour day-of-month month day-of-week year. Ele também exige o uso de ?para o dia do mês ou o dia da semana (nunca ambos como curingas ao mesmo tempo). O AWS EventBridge não suporta a sintaxe de passo */ da mesma forma que o cron Unix.

# AWS EventBridge cron format (6 fields, year at end)
cron(0 9 ? * MON-FRI *)    # Weekdays at 9 AM UTC, any year
cron(0 0 1 * ? *)           # First day of every month at midnight

Como usar o Parser de Cron do BrowseryTools

Escrever uma expressão cron do zero é uma habilidade — validar que você a escreveu corretamente é outra. O Parser de Cron do BrowseryTools torna trivial verificar qualquer expressão antes que ela chegue perto da produção.

Cole qualquer expressão cron de 5 campos (ou de 6 campos) na ferramenta e obtenha instantaneamente:

• Uma descrição legível por humanos do agendamento ("Todo dia útil às 9h"), para que você possa verificar rapidamente se sua intenção corresponde à sua expressão.
• Os próximos 5 a 10 horários de execução agendados listados explicitamente, para que você veja exatamente quando a tarefa vai disparar e confirme que não há surpresas.
• Feedback instantâneo sobre sintaxe inválida — útil se você tem um erro de digitação ou está trabalhando com uma expressão que outra pessoa escreveu.

Tudo roda inteiramente no seu navegador — nenhuma expressão é enviada a qualquer servidor. É a forma mais rápida de conferir a sanidade de um agendamento antes de implantar no GitHub Actions, no Kubernetes ou em qualquer outra plataforma.

Tabela de referência de expressões cron

Use esta tabela como referência rápida. Adicione esta página aos favoritos e volte a ela sempre que precisar consultar um padrão ou verificar o que uma expressão significa.

Valide suas expressões cron antes de implantar

As expressões cron são compactas e poderosas, mas sua concisão significa que um único erro de digitação pode silenciosamente produzir um agendamento completamente diferente. Uma tarefa que você pretendia rodar mensalmente pode rodar diariamente. Um backup que você queria acionar todo domingo pode nunca rodar. O custo de um agendamento errado em produção pode variar de um relatório perdido a uma tarefa de cobrança que dispara centenas de vezes.

O hábito de dois minutos de colar sua expressão em um validador e revisar os próximos horários de execução agendados antes de implantar é uma das práticas de maior valor em DevOps e engenharia de backend. Ele captura erros antes que eles se tornem incidentes.