Docker Hub Tag/Digest Delta Monitor

Watch Docker Hub image repositories for new tags and digest pointer changes on mutable tags (latest, stable, …) via the official Hub JSON API. Only deltas since the last run are written to the dataset — ideal for scheduled base-image and dependency monitoring.

Pricing (pay per event): charged mainly for each new tag or digest change detected (digest-change @ $0.001). First run baselines quietly (0 dataset items / 0 delta charges) so you are not billed for history. Same baseline-safe PPE shape as the live GitHub Releases Delta Monitor.

Why use this

• API-only — official Docker Hub Hub HTTP JSON (/v2/.../tags); no HTML scraping of hub.docker.com UI
• Digest-aware — fingerprints are tag + digest, so mutable tags fire when the pointer moves
• Delta-only — subsequent runs emit new tags and digest changes only
• First-run safe — empty state seeds LAST_SEEN with zero PPE delta charges
• Optional tag allowlist — watch just latest / stable without inventorying every historical tag
• Optional Hub token — higher rate limits; public repos work without one
• Schedule-friendly — pair with an Apify schedule for continuous monitoring

Input

Field	Required	Description
images	yes	List of namespace/repository (or official short names like nginx → library/nginx)
tags	no	Tag allowlist (e.g. ["latest","stable"]); empty = all tags within page budget
hubToken	no	Docker Hub PAT (secret) as Authorization: Bearer
sinceTag	no	On first run for an image, treat this tag and older (newest-first) as already seen
maxPages	no	Max Hub tags pages per image (default 2)
pageSize	no	Hub page_size 1–100 (default 100)
resetState	no	Clear LAST_SEEN and re-baseline (0 emits that run)

Example

{
  "images": ["library/nginx", "library/python"],
  "tags": ["latest", "stable"],
  "maxPages": 2,
  "pageSize": 100,
  "resetState": false
}

Output

Each dataset item is a newly detected tag or digest change, for example:

• image, tag, digest, previous_digest, change_kind (new-tag | digest-change), last_updated, full_ref, hub_url

First-run behavior

Situation	Dataset items	digest-change charges
Empty state, no sinceTag	0	0 (baseline only)
Empty state + sinceTag	Only newer-than that tag (newest-first)	1 per item
Later runs	New tags + digest pointer moves	1 per item

Mutable tags — read carefully

Tags like latest, stable, or 3 are mutable: the same name can point at a new content digest after a rebuild or roll-forward. This Actor:

• Stores fingerprints as tag:{name}:digest:{sha256:…}
• Emits a digest-change when the digest for a known tag name changes
• Emits a new-tag when a tag name appears for the first time in the watched set

Pin immutable digests in production deploys when you need bit-for-bit reproducibility; use this Actor to detect when mutable pointers move.

Tips

1. Run once to baseline, then attach a schedule (e.g. hourly/daily).
2. Prefer a tag allowlist for busy official images (thousands of tags).
3. Add a hubToken if you monitor many repos (anonymous Hub rate limits are lower).
4. Set a user max total charge on the run so costs stay predictable.

ToS / scope

Uses Docker Hub’s official Hub HTTP JSON API only (tag list endpoints under https://hub.docker.com/v2/...). Digests are taken from API fields — never invented. See ./AGREEMENT.md. Respect Hub rate limits and terms. Private registries are out of scope for v0.