Rule types

Rules define how Planekeeper measures version staleness. Each rule type calculates a "behind by" value and compares it against three severity thresholds you configure: moderate, high, and critical.

How thresholds work

Every rule has three threshold tiers. Thresholds must be ordered from smallest to largest:

Threshold	Severity	Meaning
moderate	Moderate	First level of concern
high	High	Significantly behind
critical	Critical	Immediate attention required

The highest matching threshold wins. If the behind-by value is below the moderate threshold, no alert is generated.

Example: A rule with thresholds moderate=7, high=30, critical=90:

• Behind by 5 days: no alert
• Behind by 10 days: moderate alert
• Behind by 45 days: high alert
• Behind by 100 days: critical alert

---

Days behind

Alerts when your deployed version was released more than N days ago, measured from the deployed version's release date to today.

Parameter: max_days (set via the three threshold fields)

How it calculates:

1. Look up the release date of your discovered (deployed) version in the upstream releases
2. Calculate the number of days between that release date and today (time.Since(deployedReleaseDate))
3. Compare against your thresholds

The latest version's release date is not used in this calculation. Only the deployed version's release date and the current date matter.

Example (assuming today is Mar 15):

Your version	Released on	Days since release (to today)	Behind by
1.25.0	Jan 29	45 days	45 days
2.0.0	Mar 10	5 days	5 days
3.1.0	Dec 6	99 days	99 days

With thresholds of moderate=30, high=60, critical=90:

• Version 1.25.0: 45 days since release = moderate
• Version 2.0.0: 5 days since release = no alert
• Version 3.1.0: 99 days since release = critical

Version not found

If your deployed version does not exist in the upstream releases (for example, a custom build or fork), Planekeeper marks it as critical with a behind-by value of -1. Update your gather job configuration to ensure the deployed version appears in the release list.

---

Majors behind

Alerts when your deployed version is N or more major versions behind the latest release.

Parameter: max_majors (set via the three threshold fields)

How it calculates:

1. Parse both your deployed version and the latest version as semantic versions
2. Subtract the major version numbers: latest_major - deployed_major

Example:

Your version	Latest version	Calculation	Behind by
1.5.2	3.1.0	3 - 1	2 majors
2.0.0	2.9.5	2 - 2	0 majors
5.3.1	8.0.0	8 - 5	3 majors

With thresholds of moderate=1, high=2, critical=3:

• Version 1.5.2 vs 3.1.0: 2 majors behind = high
• Version 2.0.0 vs 2.9.5: 0 majors behind = no alert
• Version 5.3.1 vs 8.0.0: 3 majors behind = critical

Parse failures

If either version string cannot be parsed as a semantic version (for example, latest or nightly-build), the alert is marked critical with a behind-by value of -1. Use version transforms on your scrape job to normalize version strings into semver format.

---

Minors behind

Alerts when your deployed version is N or more minor releases behind the latest. This rule counts actual releases, not version number gaps.

Parameter: max_minors (set via the three threshold fields)

How it calculates (preferred method):

1. Collect all upstream releases between your deployed version and the latest
2. Count unique major.minor combinations in that range
3. Use that count as the behind-by value

This means skipped version numbers do not inflate the count. If a project releases 1.1, 1.2, 1.5, and 1.8 (skipping 1.3, 1.4, 1.6, 1.7), only four minor releases are counted.

Example with release-list counting:

Available releases: 2.0.0, 2.1.0, 2.2.0, 2.3.0, 2.4.0, 3.0.0, 3.1.0

Your version	Latest	Unique minors between	Behind by
2.2.0	3.1.0	2.3, 2.4, 3.0, 3.1	4 minors
2.4.0	3.1.0	3.0, 3.1	2 minors
3.0.0	3.1.0	3.1	1 minor

Fallback calculation:

When the full release list is unavailable, Planekeeper uses a formula:

• Same major version: latest_minor - deployed_minor
• Different major versions: (latest_major - deployed_major) + latest_minor

This is an approximation and may overcount when major version boundaries are crossed.

---

Stable-only filtering

Enable the stable_only flag on a rule to ignore prereleases when determining the latest version. When enabled, Planekeeper skips any release whose version string contains:

alpha, beta, rc, dev, snapshot, canary, nightly, pre

The check is case-insensitive, so 1.0.0-RC1, 2.0.0-beta.3, and 3.0.0-SNAPSHOT are all treated as prereleases.

Example:

Available releases (newest first): 5.0.0-rc1, 4.2.0, 4.1.0, 4.0.0

stable_only	Latest version used	Notes
Off	5.0.0-rc1	Compares against the prerelease
On	4.2.0	Skips the RC, uses the latest stable

When to use stable_only

Enable stable-only filtering when you track production deployments that should only follow stable releases. Leave it off if your deployment pipeline tracks release candidates or beta versions intentionally.

---

Choosing the right rule type

Scenario	Recommended rule type	Why
Security-sensitive applications	days_behind	Time-based detection catches any stale version regardless of versioning scheme
Frameworks with breaking changes per major	majors_behind	Tracks the effort level of upgrading
Rapidly iterating projects	minors_behind	Counts actual releases you have missed
Mixed versioning strategies	Combine multiple rules	Create separate alert configs with different rule types for the same scrape+gather pair