Changelog & Release Tracker — Do I Need To Upgrade?

A release feed is easy and nearly useless: a list of version numbers and a wall of markdown. The question you actually have is narrower:

I'm on 4.2.1. How far behind am I, is any of it a security fix, and will upgrading break me?

This reads the release notes rather than listing them, and answers that in one field.

Tracks GitHub and npm. No API key, no login.

What makes it different

Give it your current version and you get a verdict, not a feed:

urgency	What it means
security	A release in the gap contains a security fix. Upgrade now.
plan_upgrade	Breaking changes or a major bump in the path. Needs a planned change, not a bump.
drifting	10+ behind with nothing breaking flagged — but the longer you wait the harder it gets.
low	Behind, and the newest release is over a year old. The project may be dormant.
routine	Fixes and features only.
current	Nothing to do.

Real output from a live run:

vercel/next.js: at least 2 releases behind, and the path includes breaking changes (major version bump). Read the notes before upgrading — this needs a planned change, not a bump. Your version predates the releases fetched, so the real gap is larger — raise maxReleasesPerProject for an exact count.

Note the "at least". Only a window of recent releases is fetched, so if your version predates that window the count is a floor, not the answer — and it says so rather than reporting a confident wrong number. versionsBehindIsLowerBound carries the same fact as a field.

What you get

Field	Description
version · publishedAt · url · author	The release
hasSecurityFix	Security section, CVE or GHSA id in the notes
hasBreakingChanges	Breaking-changes heading or a BREAKING CHANGE token
hasDeprecations · hasFeatures · hasFixes	What else is in there
versionsBehind · versionsBehindIsLowerBound	The gap, and whether it's exact
urgency · action	The verdict, in one sentence
notesEmpty	Nobody wrote release notes — not the same as nothing changing
notesUnavailable	npm rows: the registry publishes no notes at all
isNewSinceLastRun	For scheduled watching

Input

{
  "repositories": ["facebook/react@19.0.0", "vercel/next.js@14.0.0"],
  "npmPackages": ["axios@1.6.0"]
}

Append @<your version> to get a verdict. Without it you just get the release list.

As a watcher (the way to run it)

{
  "repositories": ["facebook/react", "vercel/next.js"],
  "onlyNewSinceLastRun": true
}

Schedule it, attach a webhook, and you're notified only when something actually ships — not every time it runs.

Sample output

[
  {
    "project": "vercel/next.js",
    "version": "16.3.4",
    "publishedAt": "2026-08-28T14:02:11Z",
    "hasBreakingChanges": true,
    "hasSecurityFix": false,
    "currentVersion": "14.0.0",
    "latestVersion": "16.3.4",
    "versionsBehind": 2,
    "versionsBehindIsLowerBound": true,
    "urgency": "plan_upgrade",
    "action": "at least 2 release(s) behind, and the path includes breaking changes (major version bump)...",
    "status": "ok"
  }
]

GitHub rate limits — why there's a token field

GitHub's REST API allows 60 requests an hour without a token. So by default this uses the public releases.atom feed, which has no rate limit.

Supply a token (a read-only one with no scopes is enough) and it uses the REST API instead: 5,000 requests/hour, plus proper draft and prerelease flags and author names. If the token is rejected it falls back to the feed and records that in PROJECT_SUMMARY rather than failing.

Pricing

$1.50 / 1,000 releases ($0.0015 per result), plus a near-zero start fee. Tracking 20 projects weekly costs a few cents. Never charged beyond maxItems.

⚠️ Read before you rely on it

• The flags are only as good as the notes. They're derived from what the maintainer wrote. A project that ships a breaking change without documenting it will not be flagged — notesEmpty tells you when there was nothing to read, which is itself a signal.
• npm rows carry no notes. The registry publishes versions and dates only, so those flags are null, not false. Unknown is not the same as absent, and they aren't conflated.
• Prereleases are excluded by default. Nobody is "twelve releases behind" because of nightly canaries. Turn includePrereleases on if you track them.
• versionsBehind is bounded by maxReleasesPerProject. Check versionsBehindIsLowerBound before quoting the number.

FAQ

• Do I need a GitHub token? No — only if you track many repos or want the richer API fields.
• Does it work on private repos? Only with a token that can read them.
• Can it watch changelog files instead of releases? Not yet — it reads GitHub Releases and the npm registry. A project that only maintains a CHANGELOG.md and never tags releases won't be picked up.
• How do I get alerts? Set onlyNewSinceLastRun, schedule the actor, and add a webhook on "run succeeded".

Related actors

• Dependency Vulnerability Advisor — which of your dependencies are vulnerable, and what to upgrade to.
• npm Package Info — maintenance health and abandonment risk.
• GitHub Repository Scraper — activity and health of the upstream project.