# Herald and GitHub Releases — when to use each, and why most teams need both GitHub Releases is great for your engineering audience. It's invisible to your users. Herald reads your PRs to draft the customer-facing changelog AND publishes back to GitHub Releases — so you don't have to choose. GitHub Releases is GitHub's built-in feature for marking versioned releases on a repository. It's discoverable by developers via the GitHub UI and API, but invisible to product users. A customer-facing changelog tool serves the second audience. Herald uses GitHub Releases as a source AND a publishing destination — bidirectional integration that keeps both surfaces in sync with one source of truth. Published: May 2026 Last reviewed: 2026-05-28 Author: Herald Team Category: GitHub Integration Read time: 7 min read Tags: GitHub Releases, GitHub, Bidirectional integration ## Two audiences, two surfaces Every shipping team has the same realization eventually: their engineering changelog and their customer changelog are not the same document. The engineering version lives close to the code. It's a list of PRs merged, tags cut, versions bumped. The audience is other engineers, contributors, downstream library consumers, integrators wiring against your API. They want commit hashes, breaking-change callouts, semver compliance, links back to the diff. GitHub Releases is exactly this. It's good at it. The customer version lives close to the product. It tells the people who actually use the thing what changed in their world. The audience is the product user — non-technical, busy, paying. They want to know: did the bug that's been annoying me get fixed? Is there a new feature I should look at? Did anything I rely on change? They don't want to read a PR title. They want a clean sentence in their inbox or in a "What's new" widget inside the app. For a long time, teams have been forced to maintain both, by hand, in two different places. That's the gap Herald exists to close. ## What GitHub Releases is good at GitHub Releases is the right tool for engineering communication. Its strengths: - **Lives at the source of truth.** A release is anchored to a git tag. The version in the release equals the version that was deployed. There's no drift between "what we said shipped" and "what actually shipped." - **Discoverable to engineers.** Every developer who lands on the repo sees Releases as a top-level navigation item. Anyone tracking your project for upstream changes uses Releases as the canonical source. - **API-accessible.** Tools like Dependabot, Renovate, and dozens of CI scripts watch the Releases API to detect new versions. If you're shipping a library or SDK, your Releases drive automation that other people depend on. - **Free, no extra tool.** You get it just by being on GitHub. - **Auto-draft from PRs.** GitHub's "Generate release notes" button can draft notes from PR titles and labels between two tags. It's basic, but it's free and it works. If your only audience is engineers reading your repo, GitHub Releases alone is fine. You probably don't need a changelog tool. ## Where it falls short for users The problem is GitHub Releases isn't *for* end users. It assumes its reader: - Has a GitHub account, or at least knows where to look. - Is comfortable parsing terms like "regression," "hotfix," "v2.4.0-rc.1," and "deprecated." - Is willing to navigate to a repo, click Releases, scroll through entries. - Doesn't need an email when something ships. - Doesn't need an in-app widget. - Doesn't need anything segmented by user audience, plan tier, or beta enrollment. For a SaaS team whose customers are operators, designers, marketers, or other non-engineering humans, that's nearly nobody who'll ever read GitHub Releases. The information goes into the void. There's also a second-order SEO problem: GitHub Releases pages don't rank well for product-name queries. They're hosted on github.com, the title is the version number, and the content is engineering jargon. Your customer searching "[your product] new features" will never find your GitHub Releases page. ## What a changelog tool gives you A dedicated customer-facing changelog handles all the things GitHub Releases doesn't: - A hosted page at `changelog.yourapp.com` (or wherever you want), branded to your product, indexed by Google for your customer-facing search terms. - An embeddable widget that lives inside your app with an unread count, so users see updates without having to navigate anywhere. - Email notifications to opted-in subscribers when something ships. - Segmentation: show beta users different content than free users, show enterprise customers the parts that matter to them. - Plain-English copy, written for the people who pay you, not the people who write your code. The downside historically was that you had to write all of that *separately* from your engineering release process. Two pipelines, two voices, two sources of truth, and a permanent risk that they'd drift out of sync. ## Herald reads from AND publishes to GitHub Herald collapses the duplication. The same GitHub history that powers your engineering Releases also drafts your customer-facing changelog — and the customer-facing release publishes back to GitHub. The bidirectional integration has three pieces: 1. **Import**: Herald reads your repo. You can draft a release from a branch-to-branch diff, a release/tag-to-tag diff, or merged PRs in a time range. The AI drafts the entries from your repo history. (You can also cherry-pick manually if you want full control.) 2. **Author**: You review the draft in Herald's editor. Reorder items, drop the ones that don't matter to customers, rewrite anything that came out too technical. The voice and audience shift from engineer to user happens here, on top of source-of-truth data. 3. **Publish back**: When you publish in Herald, the same release can publish to GitHub Releases too — with optional draft-sync and an optional attribution footer. The version, title, and items match. Two surfaces, one source of truth. This bidirectional loop — read your PRs to draft, then publish the finished release back to GitHub Releases — is the part most changelog tools aren't built around. Other tools in the category position differently (Headway and Beamer are written-in-editor changelogs; AnnounceKit imports GitHub Releases one-way; FeatureBase syncs GitHub Issues into feedback boards). Herald is built around the PR-to-changelog-to-GitHub-Releases loop specifically. ## How the bidirectional flow works In practice, a release cycle looks like this: 1. Engineers merge PRs into `main` as normal. No process change. 2. When you're ready to cut a release, start a new release in Herald and pick one of the three AI source modes: merged PRs since a date, compare branches, or compare releases/tags. 3. Herald drafts the customer-facing entry with AI, grouped into categories (Feature, Improvement, Fix, etc.). 4. Review. Edit anything that needs more user-friendly framing. Drop internal-only changes. 5. Hit Publish. The release appears on your hosted changelog page, in the widget, and in subscriber email — and, if you've enabled GitHub publish-back in your integration settings, on your GitHub Releases page too with the optional attribution footer. End state: one publish action, two audiences served, zero copy-paste. ## Set it up To enable bidirectional GitHub on a Herald project, you need a Team+ plan. 1. In your project's GitHub integration settings, connect your repo. Public repos work with just the repo path. Private repos need the Herald GitHub App installed (it needs `contents: write` permission to publish back). 2. Enable publishing back to GitHub Releases. You can also opt to sync Herald drafts as GitHub drafts for pre-publish visibility, and add an attribution footer if you want one. 3. Save. That's it. The next release you publish in Herald appears in both places automatically. (Exact menu labels and toggle names may evolve — check the in-app integration settings for the current copy.) --- Ready to stop maintaining two changelogs? [Start a 14-day Herald trial](https://app.sendherald.com/sign_up) with full Team features, no credit card. Connect your repo, draft a release from your last 30 days of merged PRs, and see it land in both your customer-facing changelog and your GitHub Releases page. Next guide: [AI release notes — what they are, how the good ones work, and how to pick one](/guides/ai-release-notes/)