Cron expression for every year

Field breakdown

Next runs

How this schedule works

Cron evaluates the five fields of 0 0 1 1 * — minute, hour, day of month, month, day of week — against the clock once a minute and starts the job on any minute where all five match, which cronstrue reads as "At 12:00 AM, on day 1 of the month, only in January": one run per year. Day of month is pinned to 1 and the month field selects January, while day of week stays an asterisk — so the run lands on whatever weekday that date happens to be, and never drifts to a neighbouring day.

When to use every year

An annual schedule is for archive and retention sweeps, rotating a yearly certificate or key, and resetting counters at the turn of the year. It is also the schedule most likely to be broken by the time it finally runs, because a year is long enough for the surrounding code to change, for credentials to expire, and for everyone who wrote it to have moved on. Treat the expression as a statement of intent, and make the job runnable on demand so that it can be exercised long before January 1 arrives.

Common mistakes with every year

Cron has no year field, so an annual expression means "every January 1, forever" and there is no way to scope it to a single year. For a genuine one-off, use the at command or guard the job with a date check. The real hazard, though, is decay. Twelve months is long enough for the runtime to be upgraded, the credentials to be rotated, the bucket to be renamed and the author to have left, and the job's one annual attempt is not the moment to discover any of it. Rehearse it in a non-production environment on a schedule you can actually observe.

Platform snippets

The same expression, ready to paste into the four schedulers that read five-field cron. The notes below each snippet are the ones that follow from this schedule; the cron expression generator lists every caveat for every platform.

name: Scheduled workflow
on:
  schedule:
    - cron: '0 0 1 1 *'
  workflow_dispatch:

jobs:
  scheduled:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run job
        run: echo "Running scheduled job"

apiVersion: batch/v1
kind: CronJob
metadata:
  name: my-cron-job
spec:
  schedule: "0 0 1 1 *"
  jobTemplate:
    spec:
      template:
        spec:
          containers:
            - name: job
              image: my-image:latest
              command: ["/bin/sh", "-c", "echo Running"]
          restartPolicy: OnFailure

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "crons": [
    {
      "path": "/api/cron",
      "schedule": "0 0 1 1 *"
    }
  ]
}

# Edit your crontab: crontab -e
0 0 1 1 * /path/to/command

# With logging:
0 0 1 1 * /path/to/command >> /var/log/cron.log 2>&1

Variations

• 0 0 1 7 * At 12:00 AM, on day 1 of the month, only in July July 1. An annual job does not have to land on New Year's Day, and a mid-year date avoids the holiday when nobody is on call.
• 0 0 1 */6 * At 12:00 AM, on day 1 of the month, every 6 months January and July. Two runs a year means the schedule is exercised twice as often, which is worth more than it sounds for rarely-run code.
• 0 0 1 */3 * At 12:00 AM, on day 1 of the month, every 3 months Four runs a year. If an annual sweep keeps timing out on the volume it has accumulated, quartering it is usually the cheapest fix.
• 0 9 1 1 * At 09:00 AM, on day 1 of the month, only in January January 1 at 09:00. Midnight on New Year's Day is the least-staffed hour of the year, which is a poor time for a once-a-year job to fail.