Source: https://docs.planekeeper.com/recipes/monitor-github-releases/
Site: Planekeeper Docs
Title: Monitor GitHub releases
Description: Full walkthrough for monitoring GitHub project releases, including GitHub token setup for higher rate limits.

***

# 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](https://github.com/settings/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

> **warning:** 
**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) |

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:

| 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) |

4. Click **Create**

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

> **success:** 
**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 |

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:

| Field | Value |
|-------|-------|
| Name | `Traefik Version Check` |
| Scrape Job | Select `Traefik Deployed Version` |
| Gather Job | Select `Traefik Releases` |
| Rule | Select `Days Behind Check` |

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.

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