Glossary

A

Acknowledgment

Marking an alert as reviewed. Acknowledging an alert does not resolve it – it signals that someone has seen it and is aware of the issue. Acknowledgment resets automatically if the deployed version changes.

Agent

A lightweight worker process that executes gather and scrape tasks. Agents poll the API server for pending work, run the task locally, and report results. See also: server agent, client agent.

Alert

A record indicating that a monitored version violates a rule. Each alert has a severity (moderate, high, or critical) and a behind-by value showing how far the deployed version is from the latest.

Alert config

The connection point that links three things together: a scrape job (deployed version), a gather job (upstream releases), and a rule (how to measure). Each alert config can have at most one active alert at any time.

API key

A credential used to authenticate agents, scripts, and the admin UI. Format: pk_<id>_<secret>. Passed via the X-API-Key header or the planekeeper_api_key cookie.

B

Behind-by value

A numeric measure of how far a deployed version is from the latest upstream version. The unit depends on the rule type: days for days_behind, major version distance for majors_behind, or minor version count for minors_behind.

C

Client agent

An agent deployed at a remote site, outside the main Planekeeper infrastructure. Useful for scraping private repositories that are not accessible from the server’s network. Requires an API key for authentication.

Cron expression

A schedule string that defines when a job runs. Uses standard cron syntax with five fields: minute, hour, day-of-month, month, day-of-week. Example: 0 */6 * * * runs every 6 hours.

D

Dead letter

A notification delivery that has exhausted all retry attempts. Dead letters can be manually retried from the UI or API. Deliveries move to dead letter status after approximately 16 hours of failed attempts.

G

Gather job

A job that fetches the latest available versions from an upstream source (GitHub releases, a Helm repository, or an OCI container registry). Gather jobs store their results as upstream releases.

M

Manual scrape job

A scrape job configured with the manual parse type. Instead of extracting versions from Git repositories, users enter the version string directly via the UI or API. This enables the full monitoring pipeline (rules, alerts, notifications) without requiring agent infrastructure. Useful for demos, testing, and environments where agent deployment is not practical.

H

HMAC signing

A method of verifying webhook authenticity. When a secret is configured on a notification channel, Planekeeper signs each webhook payload using HMAC-SHA256. The receiving system can verify the signature to confirm the webhook came from Planekeeper.

N

Notification channel

An endpoint where Planekeeper sends alert notifications. Currently supports webhooks (HTTP POST to a URL). Channels can have custom templates for platforms like Discord, Slack, Teams, and PagerDuty.

Notification delivery

A single attempt to send a notification to a channel. Deliveries track their status (pending, in progress, succeeded, failed, dead letter), retry count, and response details.

Notification rule

A routing rule that determines which alert events go to which channels. Rules can filter by severity level and event type. Multiple rules can be active simultaneously, each routing to different channels.

O

Organization

The top-level tenant boundary. Every resource belongs to an organization. Users can be members of multiple organizations and switch between them.

P

Parser

The component that extracts a version string from a file. Four types are available: YQ for YAML files, JQ for JSON files, Regex for any text file, and Manual for direct user-entered versions (no file or agent required).

Policy document

An AWS IAM-style JSON document that describes a role’s permissions. Contains statements with Allow/Deny effects, action patterns (like gather-jobs:list or *:* for full access), and resource scope. Used when creating or editing custom roles.

R

Rule

A definition of how to measure version staleness. Specifies a rule type (days_behind, majors_behind, or minors_behind) and three severity thresholds (moderate, high, critical).

S

Scope

A filter that controls which resources you see in list views. Three scopes are available: Organization (your resources only), Global (shared resources), and All (both).

Scrape job

A job that extracts a deployed version from a file in a Git repository. The agent clones the repository, reads the target file, and applies a parser expression to extract the version string. Results are stored as version snapshots.

Server agent

An agent that runs alongside the API server within the same network. It auto-provisions its own API key from the database and does not require manual credential configuration.

Severity

The urgency level assigned to an alert. Three levels exist:

• Moderate – the deployed version is starting to fall behind
• High – the version gap is significant and should be addressed
• Critical – the version is severely behind and requires immediate attention

Source type

The origin system for a gather job. Supported types:

• github_releases – GitHub repository releases
• helm_repository – Helm chart repository index
• oci_registry – OCI container registry

Stable only

A flag on rules that excludes prerelease versions (alpha, beta, RC, dev, snapshot, canary, nightly, pre) from comparisons. When enabled, only stable releases are considered.

T

Task execution

A single run of a gather or scrape job by an agent. Each execution receives a unique token for tracking and idempotency. Executions have a timeout (default 5 minutes) and are automatically recovered if the agent disconnects.

U

Upstream release

A version record fetched by a gather job. Stores the version string, release date, whether it is a prerelease, and the source artifact name.

UTC (Coordinated Universal Time)

The timezone used for all timestamp storage in Planekeeper. The UI automatically converts timestamps to your browser’s local timezone. Date-only fields (such as release dates) always display as the UTC calendar date. API responses use RFC 3339 format with a Z suffix (e.g., 2026-01-15T14:30:00Z).

V

Version snapshot

A point-in-time record of a deployed version discovered by a scrape job. Every scrape creates a new snapshot, even if the version has not changed, enabling tracking of version changes and rollbacks over time.

Version transform

An optional post-parse transformation applied to extracted version strings. Available transforms: add_v_lower (prepend lowercase v), add_v_upper (prepend uppercase V), strip_v_lower (remove lowercase v prefix), strip_v_upper (remove uppercase V prefix).