Connecting GitHub to Herald

Two ways to connect (public vs private)

Open your project's Settings → Integrations → GitHub to connect a repository. There are two paths depending on whether the repo is public or private.

Public repo via repo path

For public repos, paste the repo path (e.g. owner/repo) in the GitHub section. No OAuth needed — Herald reads publicly available PR and commit data directly. This works on every paid plan including Solo.

Private repo via the Herald GitHub App

For private repos, install the Herald GitHub App on the repository (or the whole organization). The app requests contents: write permission so it can both read your PR history AND publish releases back to GitHub Releases when you enable bidirectional publishing.

Private repos require a Team+ plan.

Legacy user token

Existing accounts can keep using the legacy user-token auth flow if they're already on it. New connections should prefer the GitHub App — it scopes permissions per-repository and supports the publish-back-to-Releases flow.

Drafting a release — three AI source modes

Open Releases → New Release in your project. The release editor's YOLO mode lets Herald draft the release with AI from one of three sources:

1. Merged pull requests in a time range — pick "Last published release," "Last 7/14/30/60 days," or a custom date range. Herald uses PR titles, bodies, and labels to draft entries.
2. Compare branches — pick a Base and Head branch. Herald drafts entries from changes in Head that are not in Base. Useful for release-candidate branches.
3. Compare releases or tags — pick a Base and Head release or tag. Herald drafts entries from changes between those two versions. Useful when your team cuts named release tags.

Pick the source mode that matches how your team thinks about a release. PR-time-range is the most common.

Selecting PRs and commits manually

If you want full control, the Select PRs & Commits mode lets you browse your repo's recent merged PRs and commits, multi-select the ones that belong in this release, and add them as items. The PR title and description become the item; you can edit either before publishing.

YOLO mode and manual select can be used together — start with YOLO to get most items drafted, then add or remove specific PRs to refine.

Editing the AI draft

Every AI-drafted item is editable. Reorder items, change category, rewrite descriptions, drop items that aren't customer-facing, or split a single PR into multiple items if it shipped more than one user-visible change.

A "Summary" section above the item list lets you add an optional intro paragraph for the release as a whole — Herald doesn't auto-generate this; treat it as your editorial voice on top of the AI-drafted item list.

Categories

Each release item is classified by category. Herald ships with five defaults:

• Feature — new capability
• Improvement — enhancement to an existing capability
• Fix — bug fix
• Security — security-relevant change
• Deprecation — feature being phased out

Categories are editable per-project under Categories in the project nav. Add custom categories that match your team's vocabulary (e.g., "API", "Mobile", "Internal").

Herald's AI suggests a category for each PR-drafted item based on the PR title, body, and labels. You can override the suggestion before publishing.

Publishing back to GitHub Releases

Herald is bidirectional with GitHub. The same release you publish to your customer-facing changelog page can also publish to your repo's GitHub Releases page in the same action.

In Settings → Integrations → GitHub → Publish releases to GitHub, you can enable:

• Publish on GitHub — push every Herald release to GitHub Releases when published.
• Also sync Herald drafts to GitHub as drafts — pre-publish drafts in Herald become drafts on GitHub too.
• Include "Posted with Herald" footer — optional attribution at the bottom of the GitHub Release body.

This requires the Herald GitHub App (it uses the contents: write permission). Bidirectional publishing is available on Team+ plans.

The customer-facing changelog page and your GitHub Releases page stay in sync without any copy-paste. One source of truth, two surfaces.

Multi-repo with parent and child projects

If your product ships from more than one repo (web app + mobile + API + docs, for example), you can set up a project hierarchy:

1. Create a parent project for the public-facing product. Don't connect a repo to it.
2. For each underlying repo, create a child project. In its Settings → General, set "Parent project" to the parent. Connect the child to its own GitHub repo.

The parent's public changelog page aggregates releases from all children, sorted chronologically and labeled by source child project. Each child still has its own release stream, subscribers, and (optionally) its own widget.

This avoids the two compromises most teams make: collapsing into a monorepo for the changelog's sake, or maintaining several disconnected changelogs your users can't follow. See the Aggregating multi-repo changelogs guide for the full walkthrough.

Project hierarchy is available on Team+ plans.

What makes a good PR for Herald

Herald's AI draft quality depends on what's in the PR. To get drafts that need minimal editing:

• Descriptive PR titles — "Add audience segmentation to widget" beats "WIP".
• PR body explains user-facing impact — what the user can now do, or what was broken before. The AI uses this to write the description.
• Labels matching your category mapping — bug → Fix, enhancement → Feature, security → Security. Add custom labels and category mappings as needed.

If your PRs are minimal (just a title), Herald's AI still drafts something — but you'll edit more. Conventional Commits-style PR titles are a good investment regardless.