Monitor GitHub releases

This recipe covers monitoring a GitHub project’s releases end to end. You will set up a gather job to track upstream releases, a scrape job to detect your deployed version, and rules to alert when versions fall behind.

The example monitors Traefik, but the steps apply to any project that publishes GitHub releases.

Prerequisites

• A running Planekeeper instance with at least one active agent
• A Git repository where you track the version of the software you deploy

Step 1: Configure a GitHub token (recommended)

Without a token, GitHub limits API requests to 60 per hour. With a token, the limit increases to 5,000 per hour.

1. Go to GitHub Settings > Developer settings > Personal access tokens
2. Generate a new token (classic) with no scopes – public repository access needs no special permissions
3. Set the GITHUB_TOKEN environment variable in your Planekeeper deployment configuration

Step 2: Create a gather job

1. Navigate to Gather Jobs in the sidebar
2. Click Create Gather Job
3. Fill in the fields:

4. Click Create

The artifact name uses the format github.com/owner/repo matching the GitHub repository path.

Optional: filter releases by tag pattern

Many projects include tags for subpackages or tooling. Use the Tag Filter field to include only relevant tags:

Optional: extract version from tag

Some projects use non-standard tag formats. Use the Version Regex field to extract a clean version string:

Step 3: Create a scrape job

1. Navigate to Scrape Jobs in the sidebar
2. Click Create Scrape Job
3. Fill in the fields:

4. Click Create

This regex extracts the version number from a Docker image tag like traefik:v2.10.4 in your compose file.

Step 4: Create a rule

1. Navigate to Rules in the sidebar
2. Click Create Rule
3. Fill in the fields:

4. Click Create

Step 5: Create an alert config

1. Navigate to Alert Configs in the sidebar
2. Click Create Alert Config
3. Fill in the fields:

4. Click Create

Step 6: Trigger an initial run

Both jobs need to complete at least once before alerts can be generated.

1. Go to Gather Jobs, find Traefik Releases, and click Run Now
2. Go to Scrape Jobs, find Traefik Deployed Version, and click Run Now
3. Wait for both jobs to complete (check their status on the jobs pages)
4. Check the Dashboard for any alerts

From this point on, the jobs run on their cron schedules and alerts update automatically.

Monitoring multiple GitHub projects

Repeat these steps for each project you want to monitor. You can reuse the same rule across multiple alert configs – for example, one “Days Behind Check” rule can be shared by every alert config that uses days_behind measurement.