Skip to content
Planekeeper is currently in alpha development. Features and APIs may change. Feedback is welcome!
Request early access to get started.

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

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

Rate limits apply across all gather jobs

All gather jobs share the same GitHub token and rate limit. If you monitor 50 projects every hour, that consumes 50+ requests per cycle. Plan your schedules accordingly.

Step 2: Create a gather job

  1. Navigate to Gather Jobs in the sidebar
  2. Click Create Gather Job
  3. Fill in the fields:
Field Value
Name Traefik Releases
Source Type github_releases
Artifact Name github.com/traefik/traefik
Schedule 0 */6 * * * (every 6 hours)
  1. 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:

Scenario Tag filter regex
Only semver tags ^v?\d+\.\d+\.\d+$
Only v2.x releases ^v2\.
Exclude RC/beta tags ^v?\d+\.\d+\.\d+$

Optional: extract version from tag

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

Tag format Version regex Extracted version
v1.2.3 (default) 1.2.3
release/1.2.3 release/(.+) 1.2.3
app-1.2.3 app-(.+) 1.2.3

Step 3: Create a scrape job

  1. Navigate to Scrape Jobs in the sidebar
  2. Click Create Scrape Job
  3. Fill in the fields:
Field Value
Name Traefik Deployed Version
Repository URL https://github.com/myorg/infrastructure.git
Target File traefik/docker-compose.yml
Parser Type regex
Parse Expression traefik:v?([\d.]+)
Schedule 0 9 * * * (daily at 9am)
  1. Click Create

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

Match the version format

Ensure the version string your scrape job extracts matches the format in the upstream releases. If the gather job stores versions as 2.10.4 but your scrape extracts v2.10.4, use a Version Transform of strip_v_lower on the scrape job.

Step 4: Create a rule

  1. Navigate to Rules in the sidebar
  2. Click Create Rule
  3. Fill in the fields:
Field Value
Name Days Behind Check
Rule Type days_behind
Moderate Threshold 30
High Threshold 90
Critical Threshold 180
Stable Only Checked
  1. 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:
Field Value
Name Traefik Version Check
Scrape Job Select Traefik Deployed Version
Gather Job Select Traefik Releases
Rule Select Days Behind Check
  1. 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.

Reusable Per-project
Rules Gather jobs
Notification rules Scrape jobs
Notification channels Alert configs