# How to aggregate multi-repo changelogs into one public release stream When your product ships from many repos — web app, mobile, API, docs — your users still want one customer-facing changelog. Here's the architecture that doesn't compromise on either side. Aggregating multi-repo changelogs means letting a single public release stream pull from several underlying repositories — each with its own commit history, release cadence, and team — without forcing them into one monorepo. Herald solves this with parent/child projects, where a parent project's public changelog aggregates releases published by its children. Published: May 2026 Last reviewed: 2026-05-28 Author: Herald Team Category: Developer Workflows Read time: 6 min read Tags: GitHub, Multi-repo, Project hierarchy ## The multi-repo changelog problem Most products that have been around for more than a couple of years ship from more than one repo. There's a web app. A mobile app, maybe two (iOS, Android). A public API and SDKs. Documentation. Marketing site. Internal admin tools. Each of those has its own engineering cadence, its own deploy pipeline, and its own concept of a "release." Your users don't care about any of that. They want to know what changed in the product they pay for. One page. One feed. One email when something new ships, regardless of which repo it came from. There are two ways teams typically reconcile that, and both of them are bad. ## The two compromises teams make **Option A — collapse everything into one repo.** Easy for the changelog. Painful for everything else. You force teams to share a monorepo so the release pipeline can be unified. CI gets slower. Deploys get more coupled. Mobile becomes a second-class citizen behind the web build. Documentation can't be released independently of the app. The tail wags the dog: an organizational choice driven by a content-publishing convenience. **Option B — accept many disconnected changelogs.** Web app has its changelog. Mobile has its own (maybe two). API has its own. Docs probably has none. Users have no idea where to look. The marketing team copy-pastes highlights into a "what's new" email once a month, which is always three weeks out of date. Search engines see five thin, semi-related changelog pages instead of one strong canonical one. Both options are working around the same gap: changelog tools assume one project per changelog. Herald is built differently. ## A third option: parent/child projects In Herald, a project can have child projects. The child has its own GitHub repo connection, its own release stream, its own subscribers, its own widget if you want one. The parent's public changelog page aggregates everything the children publish, in chronological order, with the source noted. The literal sentence from inside the app is: *"The public changelog for this top-level project can show releases from its child projects."* In practice that means: - Each repo gets its own Herald project. The web team owns the web project. The mobile team owns the mobile project. The docs team owns the docs project. Each connects its own repo, drafts releases from its own PRs, publishes on its own cadence. - A parent project exists for the public-facing brand. It aggregates everything. The hosted page at `your-product.com/changelog` (or wherever you embed the widget) shows a unified feed. - Subscribers signed up to the parent get notified about everything. Subscribers signed up to a child get notified about that child only — useful for power users who only care about, say, API changes. No monorepo. No copy-paste. No five disconnected pages. ## When to use this pattern Use parent/child projects when *both* of these are true: 1. Your product ships from more than one independent codebase or pipeline, AND 2. Your users think of the result as one product they pay for. Examples that fit: - A SaaS with a web app and a mobile app on the same plan. - A platform with an API, an SDK, and a dashboard, all separate repos. - A studio shipping a flagship app, an internal tool used by power users, and a docs site that updates independently. Examples that don't fit: - A monorepo that ships everything together. One project is enough. - Two genuinely separate products with separate billing, separate brands, separate users. Two parent projects, no hierarchy. - An open-source library with one repo and one release stream. One project, done. ## How to set it up in Herald The setup is two steps. First, create the parent project. Don't connect a repo to it — the parent is just the aggregation layer. Give it the URL slug you want the customer-facing changelog to live at (`changelog.yourapp.com` if you have a custom domain, or `your-changelog.sendherald.com` on the default). Second, for each repo that ships into this product, create a child project and link it to the parent in the child's project settings. Connect the child to its GitHub repo. Configure its widget if you want a separate per-repo widget; otherwise leave it. That's it. Drafts in the children flow into the parent's public feed when published. The parent doesn't need a repo. The children don't need to know about each other. (Exact setting names may evolve — check the in-app project settings for the current copy.) ## What lands on your public changelog The parent's public page shows every published release from every child, sorted by publish date. Each entry is annotated with its source child project so users can filter or skim by component if they want. Widget behavior is the same: drop the parent's `