Managing Sources

Managing Sources

Operational guide for managing changelog sources.

Tool Reference

Operations can be performed via CLI commands or typed MCP/agent tools. Use whichever interface is available in your context.

| Operation | CLI | Typed tool | |-----------|-----|------------| | List sources | releases list [slug] --json [--org ] [--query ] [--has-feed] [--category ] [--compact] [--limit ] [--page ] | list_catalog (filter kind: "source" to exclude products) | | Add source | releases admin source create --url [--type ] [--org ] [--feed-url ] [--primary] | manage_source action "add" with name, url, type, organization, feedurl, isprimary (type auto-detected if omitted; only pass isprimary=true when the source is the org's primary changelog — see "Primary Sources") | | Add App Store source | releases admin source create-appstore [--platform ios\|macos] [--org ] [--product ] [--storefront ] | (no typed tool yet — CLI only) | | Add video source | releases admin source create-video --org [--product ] | (no typed tool yet — CLI only) | | Edit source | releases admin source update [--primary] [--priority ] | manage_source action "edit" with identifier, isprimary, fetchpriority, name, url, type (use only when changing an already-added source; prefer setting flags on "add") | | Remove source | releases admin source delete [--ignore --reason ] | manage_source action "remove" with identifier | | Fetch releases | releases admin source fetch [--dry-run] [--max ] | manage_source action "fetch" with identifier | | Get latest releases | releases tail [slug] --json [--org ] | get_latest_releases with source, organization, limit params | | Search releases | releases search --json | search with type: ["releases"] | | Evaluate URL | releases admin discovery evaluate --json | evaluate_url with url param | | Add org | releases admin org create [--domain ] [--description ] [--category ] [--tags ] | manage_org action "add" with name, domain, description, category, tags | | Edit org | releases admin org update [--category ] | manage_org action "edit" with identifier, category | | Show org | releases admin org get --json | get_organization with identifier | | Add tags to org | releases admin org tag add | manage_org action "tagadd" with identifier, tags | | Link account | releases admin org link --platform --handle | manage_org action "linkaccount" with identifier, platform, handle | | Add product | releases admin product create --org [--category ] [--tags ] | manage_product action "add" with name, organization, category, tags | | Ignore URL | releases admin policy ignore add --org | exclude_url action "ignore" with url, organization | | Block URL | releases admin policy block add | exclude_url action "block" with url | | Get playbook | releases admin playbook | manage_playbook action "get" with organization | | Update playbook notes | releases admin playbook --notes-file (use - for stdin) | manage_playbook action "updatenotes" with organization, notes |

Valid categories (pass to manage_org/manage_product): see the enum in those tool descriptions or your system prompt. list_categories (now retired) has been folded into the two tool descriptions.

Listing Sources

Search for existing sources with optional filters:

• query — filter by name, slug, or URL
• organization — filter by org ID or slug
• product — filter by product ID or slug
• category — filter by category
• has_feed — only sources with a discovered feed URL

Use --json (CLI) for structured output. Typed tools always return JSON.

Adding Sources

Required: name and url. Optional: type (github, scrape, feed, agent — auto-detected from URL if omitted), organization (org ID or slug to associate with), feed_url (direct feed URL if known). App Store apps (appstore type) are not created this way — use create-appstore (below); source create rejects --type appstore and pasted apps.apple.com URLs with a pointer to it. YouTube channels/playlists (video type) are likewise not created this way — use create-video (below); source create rejects --type video and pasted youtube.com/youtu.be URLs.

On slug collision the API auto-suffixes (changelog → changelog-2, -3, …) and the created row in the response tells you the resolved slug — no rename-and-retry needed.

App Store sources

App Store apps need a dedicated command because the create flow resolves the iTunes listing, mints the current version as the first release, and backfills the product's avatar with the app icon:

releases admin source create-appstore  [--platform ios|macos] [--org ] [--product ] [--storefront ]

• ` accepts an apps.apple.com/.../id URL, a bare numeric track ID, or an appstore: coordinate. --platform defaults to ios (macos = Mac App Store); --storefront defaults to us`.
• Pre-create the product for a clean name. With no --product, the endpoint names a new product after the (often verbose) App Store title — e.g. "Shopify: Sell online/in person". To control the name, create the product first and reference it:

`` releases admin product create "Shopify" --org shopify releases admin source create-appstore https://apps.apple.com/us/app/shopify/id719892358 --org shopify --product shopify ``

• Keep writes serial. The endpoint resolves the listing on the fly; concurrent creates for a brand-new org/product race on the org/product slug uniqueness constraint. Add one app at a time.
• The command is idempotent on the app's track ID — re-running reports the existing source instead of creating a duplicate.

Video sources

YouTube channels and playlists need a dedicated command because the create flow resolves the channel/playlist to its Atom feed, mints a video source, and backfills current videos as releases (description-only, summarizer-cleaned, marketing-filtered):

releases admin source create-video  --org  [--product ]

• ` is a YouTube channel (youtube.com/@handle, /channel/) or playlist (/playlist?list=`) URL.
• --org is required and must already exist — unlike create-appstore, no org is derived from the channel. Pass a slug or a typed org_… id. --product optionally attaches the source to an existing product.
• The command is idempotent on the resolved feed URL — re-running reports the existing source.
• Never use generic source create for a YouTube URL. It builds a feed source whose parser drops media:group/media:description, leaving a source with titles and dates but empty release bodies — a silent failure that needs deleting and re-creating to fix. create rejects YouTube URLs with a pointer to create-video.

Naming sources and products

Don't prefix names with the org name. The org is already shown as context on every page — repeating it in each child source produces noise like "Datadog › Datadog dd-trace-py". Pick the bare, recognizable name instead.

Rules, in priority order:

1. GitHub sources → use the repo name. DataDog/dd-trace-py → dd-trace-py, vercel/next.js → next.js. That's the name devs already recognize; the owner/repo byline underneath disambiguates.
2. Website/feed sources → strip the org name if present. Datadog Browser SDK → Browser SDK, Stripe API Changelog → API Changelog.
3. Keep the org prefix only when it's part of the canonical product name. Claude Code, GitHub Actions, Google Cloud Run, Amazon S3 — people say them that way. If you strip the prefix and what's left is the actual name people use, strip. If stripping produces something nobody would recognize on its own, keep the prefix.
4. Org-level content sources keep the prefix. Datadog Blog, Vercel Engineering Blog — "Blog" alone is meaningless, and org-prefix is the standard convention. Same for "Newsroom", "Announcements".
5. Products follow the same rules. A product under Vercel should be Next.js, not Vercel Next.js. A product under Datadog whose actual name is Agent stays Agent — the org context above it already says Datadog.

When in doubt: would a developer reading this name on its own (with the org already shown above) recognize what it is? If yes, strip. If no, keep the prefix.

Grouping sources into products

Grouping sources into products. Most companies are single-product — leave productSlug/productName unset and sources attach directly to the org (the default).

Only when a company ships 2 or more genuinely distinct products — each with its own identity and release cadence (Vercel → Next.js, Turborepo, SWR; Datadog → APM, RUM, Browser SDK) — tag each discovered source with the product it belongs to: productName (canonical name, same naming rules as sources — no org prefix) and productSlug (stable kebab-case, per-org unique).

A product is a distinct offering, not:

• the company/engineering blog, newsroom, or all-in-one changelog → leave org-direct (untagged)
• the docs site or marketing feed → org-direct
• every individual GitHub repo by default — only repos that are themselves a recognized product

If you can't name 2+ distinct products with confidence, tag nothing. Spurious products are worse than none.

Organization descriptions

When creating an org, include a brief one-sentence product description. This grounds AI summaries for lesser-known products, and it's also the primary signal for the entity vector index — the unified search tool (and the registry side of hybrid search) matches on description + category, not just name. A good description noticeably improves recall.

Embedding side effects

Adding or editing an org, product, or source triggers an entity embedding into the registry vector index in the background (fire-and-forget on the worker, never blocks the write). PATCHes are gated on the embed-relevant fields (name, description, category, domain, url) actually changing, so cosmetic edits and poll-driven metadata bumps don't re-embed. There's no manual step — if a write succeeds, treat the embedding as in-flight. If you ever need to verify or backfill, run releases admin embed status and then releases admin embed entities (remote mode only).

Removing Sources

When removing discovery results, also ignore the URL to prevent re-discovery. In CLI: releases admin source delete --ignore --reason "...". With typed tools: call manage_source action "remove" then exclude_url action "ignore".

Ignored URLs (org-scoped)

A URL ignored for one org can still be valid for another org. Always scope ignores to the relevant organization.

Blocked URLs (global)

For spam domains and known-bad URLs that should never be added for any org. Use block_type "domain" to block an entire domain.

Validation Workflow

After adding a source, validate it:

1. Add the source — provide name and URL
2. Fetch — trigger a fetch (CLI: --dry-run for preview, then real fetch; typed tools: manage_source action "fetch")
3. Check results — get latest releases and verify they have titles, dates, content
4. If bad: remove the source and ignore the URL
5. If good: the source is ready for production fetches

Primary Sources

An org can have one source marked as its primary changelog — the main, company-wide changelog.

is_primary is conditional, not default. Only set it when the source you are adding is clearly the org's primary changelog:

• Onboarding a new org with a single top-level changelog (e.g. example.com/changelog) — set is_primary=true on the add.
• Adding a supplementary or secondary source to an existing org (an engineering blog, a per-product changelog, an RSS feed alongside an already-primary page) — do not set is_primary. Leave the existing primary alone.
• The task prompt doesn't mention "primary" or similar — default to not setting it.

When it does apply, set it on the add call in one step, not via a follow-up edit:

manage_source(action="add", name="Changelog", url="https://example.com/changelog", organization="example-corp", is_primary=true)

The same applies on CLI: pass --primary to releases admin source create, not a follow-up source update.

Use manage_source(action="edit", is_primary=true) (or releases admin source update --primary on the CLI) only when promoting a source you added in a prior session — never in the same flow as the add.

Playbooks

A playbook is a per-org skill for fetching that org's releases. Same mental model as the global skills in this corpus, scoped to one organization. Agents load the playbook into context alongside global skills whenever they fetch from this org — the playbook overrides general rules with the org's specific behavior (naming conventions, what counts as a release, cross-source dedup, rollup cadence).

Each playbook has two layers:

• Header — auto-generated from source metadata. Shows source types, URLs, priorities, parseInstructions, and product groupings. Regenerates automatically on every source mutation. You never edit this directly.
• Agent notes — free-form markdown that you fully control. This is the most important part of the playbook. Write it like a skill an agent will follow — imperative, action-oriented, concise — not like human documentation.

Always read the playbook before fetching or working with an org's sources. Typed tool: manage_playbook action "get" with organization param. CLI: releases admin playbook . If no playbook exists yet, one will be auto-generated on the next source mutation (create/update/delete).

Writing good agent notes

Write notes like a skill for the agent that will fetch from this org — imperative, action-oriented, concise. The reader is an agent about to do work; tell it what to do and what to watch for, not what things are.

Organize notes under these headings:

### Fetch instructions — One paragraph per source. Use imperative voice:

• What to do: "Set version=null", "Parse `` elements as version boundaries", "No filtering needed"
• What to expect: cadence, content quality, whether rendering is needed
• When to skip or deprioritize: "Only fetch when looking for launch announcements specifically"
• Cite version format examples where useful (e.g., "semver like 2.1.98")

### Traps — Concise warnings with bolded trigger labels:

• Each trap is a bullet with a bold label and a one-sentence explanation
• Example: **Doubled paths on Platform**: Relative doc links get prefixed with the source URL, producing doubled paths.
• Include disabled sources with "Don't re-discover" warnings so agents don't re-evaluate them
• Only include traps that would cause wasted work or bad data — skip informational notes

### Coverage — Two or three sentences max:

• Which sources are canonical vs supplementary
• Whether active sources cover the org's full release surface
• Any known gaps worth noting

### Release cadence — Call out rollup publishers explicitly. Some orgs don't ship incremental changelog entries at all — they publish seasonal, quarterly, or annual rollup pages that collect many features into one banner post or microsite (e.g. Shopify Editions, Brex Fall Release, Ramp quarterly blog). When this is the case, say so in the notes and tell the parser to classify matching pages as type: rollup. Example:

> Ramp publishes quarterly rollups at /blog/new-on-ramp-q*-* and monthly editions at /blog/new-on-ramp-*-edition. Classify all entries from this source as type: rollup — individual features within a rollup are not separately indexed.

The parsing-changelogs skill ("Classifying Rollups" section) covers what rollups look like and when to set the type field. Your job in the playbook is to capture the org-specific signal so future fetches don't have to re-derive it from the page.

Levels of pla

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: buildinternet
• Source: buildinternet/releases-cli
• License: MIT
• Homepage: https://releases.sh

Install and usage instructions live in the source repository linked above.