Cron expressions
Cron expression format reference for scheduling gather and scrape jobs, with common examples and tips for choosing intervals.
Gather jobs and scrape jobs use standard 5-field cron expressions to define their execution schedule. When a scheduled job completes, Planekeeper calculates the next run time from the cron expression and waits until that time to run the job again.
Format
* * * * *
| | | | |
| | | | +--- Day of week (0-6, Sunday=0)
| | | +----- Month (1-12)
| | +------- Day of month (1-31)
| +--------- Hour (0-23)
+----------- Minute (0-59)
Each field accepts:
| Syntax | Meaning | Example |
|---|---|---|
* | Every value | * * * * * = every minute |
N | Specific value | 0 9 * * * = at 9:00 |
*/N | Every N units | */15 * * * * = every 15 minutes |
N-M | Range | 0 9-17 * * * = hourly from 9am to 5pm |
N,M | List | 0 9,17 * * * = at 9am and 5pm |
Common schedules
High frequency
| Schedule | Expression | Use case |
|---|---|---|
| Every 15 minutes | */15 * * * * | Fast-moving projects, CI/CD pipelines |
| Every 30 minutes | */30 * * * * | Active development tracking |
| Every hour | 0 * * * * | General monitoring |
Standard frequency
| Schedule | Expression | Use case |
|---|---|---|
| Every 6 hours | 0 */6 * * * | Most gather jobs |
| Every 12 hours | 0 */12 * * * | Stable projects |
| Daily at midnight | 0 0 * * * | Nightly checks |
| Daily at 9am | 0 9 * * * | Morning reports |
Low frequency
| Schedule | Expression | Use case |
|---|---|---|
| Every Monday at 9am | 0 9 * * 1 | Weekly reviews |
| First of each month | 0 0 1 * * | Monthly audits |
| Weekdays at 8am | 0 8 * * 1-5 | Business-hours only |
Examples in context
Gather job: track a fast-moving project
For a project like Kubernetes that releases frequently, poll every 6 hours:
0 */6 * * *
This runs at midnight, 6am, noon, and 6pm.
Scrape job: check deployed versions daily
For a production deployment that changes during business hours:
0 9 * * 1-5
This runs at 9am Monday through Friday.
Gather job: track a slow-moving project
For a project that releases monthly or quarterly:
0 0 * * 0
This runs once per week at midnight on Sunday.
Tips for choosing schedules
Match the schedule to the release cadence. A project that releases every few months does not need hourly polling. A project with daily releases benefits from more frequent checks.
Consider GitHub API rate limits. Without a GitHub token, you are limited to 60 API requests per hour. With a token, the limit is 5,000 per hour. If you have many gather jobs, space them out or add a GitHub token to your configuration.
Stagger job start times. If you have multiple jobs, avoid scheduling them all at the same minute. Spread them across different minutes to reduce load spikes:
# Instead of all at the top of the hour:
0 */6 * * * # Job A
0 */6 * * * # Job B
0 */6 * * * # Job C
# Stagger across the hour:
0 */6 * * * # Job A
10 */6 * * * # Job B
20 */6 * * * # Job C
Scrape jobs can run less often. Your deployed version likely changes far less frequently than upstream releases. A daily or even weekly scrape schedule is sufficient for most deployments.
All times are UTC
Cron expressions are evaluated in UTC. Account for your local timezone when scheduling jobs for specific business hours.
What happens when a schedule is set
- You create or update a job with a cron schedule
- The job runs immediately (or at its next scheduled time)
- When the job completes, Planekeeper calculates the next run time from the cron expression
- The job waits in “completed” status until the scheduled time arrives
- The scheduler activates the job by setting it back to “pending”
- An available agent picks up the job and executes it
- The cycle repeats from step 3
Jobs without a schedule run once and remain in “completed” status until triggered manually.