Cron expressions

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

1. You create or update a job with a cron schedule
2. The job runs immediately (or at its next scheduled time)
3. When the job completes, Planekeeper calculates the next run time from the cron expression
4. The job waits in "completed" status until the scheduled time arrives
5. The scheduler activates the job by setting it back to "pending"
6. An available agent picks up the job and executes it
7. The cycle repeats from step 3

Jobs without a schedule run once and remain in "completed" status until triggered manually.