# Changelog & Release Tracker — Do I Need To Upgrade? (`alaudinburki/changelog-release-tracker`) Actor

Track GitHub and npm releases and get told whether to act. Reads the release notes to flag breaking changes, security fixes and deprecations, counts how many versions you are behind, and returns one urgency verdict per project instead of a wall of markdown.

- **URL**: https://apify.com/alaudinburki/changelog-release-tracker.md
- **Developed by:** [alaudin burki](https://apify.com/alaudinburki) (community)
- **Categories:** Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

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

```json
{
  "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)

```json
{
  "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

```json
[
  {
    "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.

# Actor input Schema

## `repositories` (type: `array`):

Repos to track as owner/repo or a github.com URL. Append @<your version> to get an upgrade verdict, e.g. facebook/react@19.0.0.

## `npmPackages` (type: `array`):

npm packages to track. Append @<your version> for a verdict, e.g. axios@1.6.0. Note the npm registry publishes no release notes, so those rows carry version and date only.

## `githubToken` (type: `string`):

Without a token the public atom feed is used, which has no rate limit but fewer fields. With one, the REST API is used: richer data and 5,000 requests/hour instead of 60. A read-only token with no scopes is enough.

## `maxReleasesPerProject` (type: `integer`):

How many recent releases to fetch for each project.

## `includePrereleases` (type: `boolean`):

Include alpha/beta/rc/canary builds. Off by default — nobody is 'twelve releases behind' because of nightly canaries.

## `onlyNewSinceLastRun` (type: `boolean`):

Return only releases not seen in a previous run. Turns this into a scheduled watcher: pair it with a webhook and you get notified only when something actually ships.

## `includeNotes` (type: `boolean`):

Include the release-note text on each row.

## `notesMaxChars` (type: `integer`):

Truncate release notes to this many characters.

## `snapshotKey` (type: `string`):

Key-value store key holding what was already seen. Use different keys to watch several sets of projects independently.

## `maxItems` (type: `integer`):

Hard cap on releases returned. You are never charged beyond this.

## Actor input object example

```json
{
  "repositories": [
    "facebook/react@19.0.0",
    "vercel/next.js"
  ],
  "maxReleasesPerProject": 20,
  "includePrereleases": false,
  "onlyNewSinceLastRun": false,
  "includeNotes": true,
  "notesMaxChars": 2000,
  "snapshotKey": "SEEN_RELEASES",
  "maxItems": 2000
}
```

# Actor output Schema

## `results` (type: `string`):

Releases with breaking/security flags and an upgrade verdict.

## `projectSummary` (type: `string`):

One verdict per tracked project.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "repositories": [
        "facebook/react@19.0.0",
        "vercel/next.js"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("alaudinburki/changelog-release-tracker").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "repositories": [
        "facebook/react@19.0.0",
        "vercel/next.js",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("alaudinburki/changelog-release-tracker").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "repositories": [
    "facebook/react@19.0.0",
    "vercel/next.js"
  ]
}' |
apify call alaudinburki/changelog-release-tracker --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,alaudinburki/changelog-release-tracker"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/WggcZLRvyVRTIVEqt/builds/rfRk61jDyIbRPQVfU/openapi.json