Gather jobs

Set up gather jobs to fetch upstream releases from GitHub, Helm repositories, and OCI container registries.

Gather jobs fetch the latest upstream releases from external sources and store them in Planekeeper. This is the first stage of the detection pipeline – you need upstream release data before you can compare it against your deployed versions.

What gather jobs do

A gather job connects to an upstream source, retrieves all available releases, and stores them as upstream releases in Planekeeper. Each run captures version strings, release dates, and prerelease flags.

When a gather job completes, any alert configs that reference it are re-evaluated immediately. If the latest upstream version has changed, alerts update automatically.

Source types

Planekeeper supports three source types for gathering releases.

GitHub Releases

Fetches releases from a GitHub repository’s releases page.

Source type: github_releases
Artifact name format: github.com/owner/repo (for example, github.com/kubernetes/kubernetes)
Data captured: Tag name, release date, prerelease flag, version string
Rate limits: 60 requests/hour without a token, 5,000/hour with a GitHub token

info

GitHub releases are fetched with sensible defaults (up to 10 pages of 100 releases each). Draft releases are excluded.

success

Configure a GITHUB_TOKEN on your agent to avoid rate limiting, especially if you have many gather jobs targeting GitHub.

Helm Repository

Fetches chart versions from a Helm repository’s index.yaml file. For bulk monitoring of Helm charts, see Helm Sync jobs below.

Source type: helm_repository
Artifact name format: repo-host/repo-path/chart-name (for example, argoproj.github.io/argo-helm/argo-cd). URL schemes (https://) and trailing slashes are automatically stripped.
Data captured: Chart version, app version, prerelease flag
Limits: Up to 1,000 versions per chart

info

Up to 1,000 chart versions are processed per chart.

OCI Registry

Fetches tags from OCI-compliant container registries such as Docker Hub, GitHub Container Registry (GHCR), and Quay.io.

Source type: oci_registry
Artifact name format: Standard OCI image references
Data captured: Tag name, manifest date (optional), prerelease flag

Artifact name examples:

Reference	Registry	Image
`nginx`	Docker Hub	`library/nginx`
`myuser/myimage`	Docker Hub	`myuser/myimage`
`docker.io/library/nginx`	Docker Hub	`library/nginx`
`ghcr.io/owner/image`	GHCR	`owner/image`
`quay.io/org/app`	Quay.io	`org/app`

Source config options:

Option	Default	Description
`max_tags`	100	Maximum number of image tags to process (1-10,000)
`fetch_dates`	true	Fetch manifest dates for each tag. Disable for faster runs, but release dates will be empty.
`insecure`	false	Use HTTP instead of HTTPS for registry communication

info

Docker Hub short names (like nginx) are automatically expanded to library/nginx and routed to registry-1.docker.io.

Create a gather job

Open the Gather Jobs page from the sidebar.
Click Create Gather Job.
Fill in the required fields:

Field	Required	Description
Name	No	A human-readable label for this job
Source type	Yes	`github_releases`, `helm_repository`, or `oci_registry`
Artifact name	Yes	The upstream source identifier (see formats above)
Schedule	No	A cron expression for recurring runs
Tag filter	No	A regex pattern to include only matching tags
Version regex	No	A regex to extract the version from the tag name

Click Create.

Filtering and version extraction

Tag filter

Use a tag filter regex to include only the tags you care about. Tags that do not match the pattern are excluded.

Examples:

Pattern	Effect
`^v\d`	Only tags starting with `v` followed by a digit
`^argo-cd-`	Only Argo CD chart tags (in a multi-chart repo)
`^\d+\.\d+\.\d+$`	Only strict semver tags (no prefix)

info

Leave the tag filter empty to include all tags. Invalid regex patterns are logged as warnings and fall back to no filtering.

Version regex

By default, Planekeeper strips a leading v or V prefix from tags to get the version string. Use a version regex when you need more control.

Examples:

Tag	Version regex	Extracted version
`v1.2.3`	(none needed)	`1.2.3`
`release-1.2.3`	`release-(.+)`	`1.2.3`
`chart-1.2.3-rc1`	`chart-(\d+\.\d+\.\d+)`	`1.2.3`

If the regex contains a capture group, Planekeeper uses the first captured group. If the regex matches but has no capture group, it uses the full match.

Schedule with cron expressions

Set a cron schedule to run the gather job automatically. The format uses five fields:

minute  hour  day-of-month  month  day-of-week
  *       *        *          *         *

Common schedules:

Expression	Frequency
`0 /6 * *`	Every 6 hours
`0 0 * * *`	Daily at midnight
`0 /2 * *`	Every 2 hours
`30 8 * * 1-5`	Weekdays at 8:30 AM

See Cron expressions for the full format reference.

warning

Avoid overly frequent schedules for GitHub sources. With many gather jobs and no GitHub token, you can exhaust the 60-requests-per-hour rate limit quickly.

Trigger a manual run

To run a gather job immediately without waiting for its schedule:

Open the gather job detail page.
Click Run Now.

The job status changes to pending and an agent picks it up shortly. Refresh the page to see updated results.

View upstream releases

After a gather job completes, view the releases it discovered:

Open the Releases page from the sidebar.
Use the search or filter to find your artifact.
Each release shows the version string, release date, and whether it is a prerelease.

Releases are stored permanently and accumulate over time. Each gather run upserts releases – new versions are added, and existing versions are updated if their metadata changes.

Job lifecycle

Gather jobs follow this lifecycle:

Pending – the job is waiting for an agent to pick it up
In progress – an agent is executing the job
Completed – the job finished successfully and releases are stored
Failed – the job encountered an error after exhausting retry attempts

After completion, if a cron schedule is set, the job automatically reschedules for its next run time and returns to pending when that time arrives.

info

Jobs stuck in “in progress” for more than one hour are automatically reset to pending. This handles cases where an agent crashes mid-execution.

Helm Sync jobs

If you manage many Helm charts from the same repository, creating individual gather jobs for each one is tedious. Helm Sync jobs automate this by scanning a Helm repository’s index.yaml, discovering all charts, and creating child gather jobs for each one.

How it works

The Helm Sync job fetches the repository’s index.yaml
It discovers all charts (optionally filtered by a regex)
For each chart, it creates a helm_repository gather job if one doesn’t already exist
Child gather jobs inherit default settings (schedule, tag filter, version regex) from the sync job
Optionally, charts that disappear from the repository have their gather jobs cleaned up automatically

Create a Helm Sync job

Open the Gather Jobs page from the sidebar.
Click Create Gather Job.
Select Helm Sync as the source type.
Fill in the form:

Field	Required	Description
Name	No	A label for this sync job
Repository URL	Yes	The Helm repository URL (for example, `https://argoproj.github.io/argo-helm`)
Chart filter	No	Regex to include only matching chart names (for example, `^argo-cd$` for a single chart)
Default schedule	No	Cron schedule inherited by all child gather jobs
Default tag filter	No	Tag filter regex inherited by child gather jobs
Default version regex	No	Version regex inherited by child gather jobs
Auto delete orphans	No	Remove child gather jobs when their chart disappears from the repository
Schedule	No	Cron schedule for the sync job itself (how often to re-scan for new charts)

Click Create.

Example

To monitor all charts in the Argo Helm repository:

Repository URL: https://argoproj.github.io/argo-helm
Default schedule: 0 */6 * * * (child jobs run every 6 hours)
Schedule: 0 0 * * * (re-scan for new charts daily)
Auto delete orphans: Enabled

This creates a gather job for every chart in the repo (argo-cd, argo-workflows, argo-rollouts, etc.) and keeps the list up to date as charts are added or removed.

success

Use the chart filter to limit discovery to specific charts if you don’t need all of them. For example, ^(argo-cd|argo-workflows)$ monitors only those two charts.

Managing child jobs

Child gather jobs created by a Helm Sync job are normal gather jobs — you can view, edit, trigger, and delete them individually. They appear on the Gather Jobs page with a reference to their parent sync job.

If you delete a Helm Sync job, its child gather jobs are not automatically deleted. You must remove them manually if they are no longer needed.

Suggest for Global Pool

When creating or editing a gather job or helm sync job, check Suggest for Global Pool to nominate it for inclusion in the shared global pool. An administrator reviews the suggestion and approves or rejects it. If approved, a copy of the job is created as a global job, making the upstream release data available to all organizations.

Bulk actions

Select multiple gather jobs using the checkboxes on the list page, then click Delete Selected to remove them in a single operation. Use the checkbox in the table header to select all visible items.

Tips

Start with an infrequent schedule (every one to two days) but manually trigger jobs to build up release history quickly
If you monitor a popular project, check whether a Global gather job already exists before creating your own. Use the scope filter on the Gather Jobs page to check.
For OCI registries, disable fetch_dates in the source config if you have many tags and don’t need release dates – this significantly speeds up gathering.
Use tag_filter to exclude non-version tags like latest, main, or sha- prefixed tags from OCI registries.
Use Helm Sync jobs instead of individual gather jobs when monitoring multiple charts from the same Helm repository.