Manual Version Tracking

This recipe walks through setting up manual version tracking from scratch – from creating a manual scrape job to seeing alerts when a version falls behind.

Manual version tracking is useful when:

• You want to demo or test the full Planekeeper pipeline without deploying an agent
• You track versions for systems where agent deployment isn’t practical
• You want CI/CD pipelines to report deployed versions directly

Prerequisites

• A Planekeeper account with an organization
• At least one gather job collecting upstream releases for the software you want to monitor (check the Gather Jobs page – global pre-seeded jobs may already cover your software)
• At least one monitoring rule defining your staleness thresholds

Step 1: Create a manual scrape job

1. Navigate to Scrape Jobs in the sidebar.
2. Click Create Scrape Job.
3. Select Manual Entry as the parser type. The repository, file, expression, credential, and schedule fields are hidden automatically.
4. Enter a descriptive Name (for example, production-nginx).
5. Optionally select a Version transform if the version format in your environment differs from the upstream releases (see Version Transforms).
6. Click Create.

Step 2: Create an alert config

An alert config links your scrape job to a gather job and a monitoring rule. This tells Planekeeper: “compare the version from this scrape job against releases from this gather job using this rule.”

1. Navigate to Alert Configs in the sidebar.
2. Click Create Alert Config.
3. Fill in:
   • Scrape Job: Select the manual scrape job you just created
   • Gather Job: Select the gather job that tracks the upstream releases (for example, a global nginx gather job)
   • Rule: Select a monitoring rule (for example, a days_behind rule with 90-day thresholds)
4. Click Create.

Step 3: Set a version

1. Go back to the Scrape Jobs page.
2. Expand the row for your manual scrape job.
3. In the Set Version form, enter your currently deployed version (for example, 1.24.0).
4. Click Set Version.

This creates a version snapshot and immediately triggers rule evaluation for all alert configs referencing this scrape job.

Step 4: Check for alerts

1. Navigate to Alerts in the sidebar.
2. If the version you entered is behind the latest upstream release by more than the rule’s thresholds, an alert will appear.
3. Click the alert to see the detail page with version comparison, metadata, and delivery history.

Updating the version

Whenever you deploy a new version, repeat Step 3 with the updated version string. Each new version:

• Creates a new version snapshot in the history
• Triggers rule re-evaluation for all linked alert configs
• May resolve existing alerts if the new version is within thresholds
• May create or escalate alerts if the new version still violates thresholds

Automating with the API

For CI/CD integration, set the version programmatically after a deployment:

curl -X POST https://planekeeper.example.com/api/v1/client/scrape-jobs/{id}/set-version \
  -H "X-API-Key: pk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"version": "1.25.0"}'

Replace {id} with your scrape job’s ID. This is equivalent to entering the version in the UI and triggers the same rule evaluation pipeline.

What to expect

After completing this recipe:

• Your manual scrape job has a version snapshot
• If the version violates rule thresholds, an alert is active with the appropriate severity
• Notification channels (if configured) receive alert events
• The alert detail page shows version comparison and delivery history
• Setting a new version that’s within thresholds automatically resolves the alert