# How we generate release notes from merged PRs

The release-notes agent we run on Kortix — connected to GitHub. On each release it reads the merged PRs since the last one, groups them, writes the notes, and opens a changelog PR.

Canonical page: https://openchatly.com/use-cases/release-notes

Release notes are the first thing that gets skipped under a deadline. The
information is all there in the merged PRs, but turning it into something a reader
can follow — grouped by area, in plain language, with the noise dropped — is
manual work that lands after the release is already out.

We run a release-notes agent on Kortix that does it from the PR history. On each
release, the agent reads every PR merged since the last release, groups them by
area, writes human-readable notes, and opens a PR to the changelog for review.
This write-up covers how the setup works: the trigger, the session model, and the
guardrails.

- **Team:** Kortix
- **Runs on:** Every tag or release
- **Connected systems:** GitHub
- **Mode:** Trigger-driven · changelog PR opened for review

## The problem

Writing release notes means reading back through everything that merged since the
last release, deciding what a reader cares about, and phrasing it for someone who
wasn't in the PRs. It's the kind of task that's easy to defer, so the changelog
falls behind or gets a one-line summary that helps no one.

The common fixes are incomplete. An auto-generated list of PR titles is accurate
but unreadable — internal wording, no grouping, every dependency bump included.
Writing them by hand is better but slow, and it competes with actually shipping.
Either way the notes arrive after the release, if they arrive at all.

## What we built

On Kortix, each release triggers an agent. When a tag is pushed, the release
spawns an isolated session (a cloud sandbox) with scoped access to the repository.
The agent finds the previous release, reads every PR merged in between, groups
them by area, writes notes in plain language, and opens a PR to the changelog. A
human reviews and merges.

## How it works

### Copy the setup prompt into a new session

Open your Kortix workspace, start a new session, paste this prompt and send it.
The agent writes the agent file, the changelog-sync skill and the hourly
trigger, and opens a change request for you to review. Prefer clicks? Choose
**Use this template** instead.

**Setup prompt**

```
Set up a release-notes agent in this workspace.

1. Create the agent agents/release-notes.md. Its job is to turn each new release of owner/repo into changelog notes and open a pull request against CHANGELOG.md. It may use the GitHub connector and the gh CLI with the GH_TOKEN secret.

2. Create the skill skills/changelog-sync/SKILL.md with these rules:
   - Keep the last release tag covered as a checkpoint in memory/changelog-sync-log.md. Cover every release published after it, oldest first. Advance the checkpoint even when a release has nothing to publish.
   - Read every PR merged between the previous tag and the new one in full: title, description, labels and files.
   - Drop PRs labeled internal, chore, ci, dependencies or no-changelog, and PRs whose title starts with chore(deps), ci: or test:.
   - Group the rest into Features, Fixes, Performance and Breaking changes. Write one plain-language line per change, and match the format that CHANGELOG.md already uses.
   - Open one PR per release that changes only CHANGELOG.md. If a changelog PR is still open, extend it. Never open an empty PR.
   - Never merge, tag, publish or announce a release. A person reviews the wording and merges.

3. Add a cron trigger release-notes-check to kortix.yaml. It runs the release-notes agent every hour, on the hour with the prompt "Load the changelog-sync skill and check owner/repo for any release published since the last checkpoint."

4. Tell me which of these connectors are not connected yet. Tell me if the GH_TOKEN secret is missing.

5. Open a change request with all of it. Do not merge it.
```

### Connect your tools

Open **Connectors** in your workspace and connect GitHub. Credentials are
brokered server-side and never enter the agent's machine. Then add a GitHub
token as the `GH_TOKEN` secret for the gh CLI. It is injected at runtime and
scoped to this agent.

- **GitHub** (Required):
Reads PRs merged since the last release and opens the changelog PR.

### Run it once with this prompt

Merge the change request, then start a session with the **release-notes** agent
and send this prompt. Replace owner/repo with your repository. Read the
changelog PR it opens before you let the schedule take over.

**Prompt**

```
Draft release notes for the latest release of owner/repo.

1. Find the newest release tag and the tag before it.
2. Read every PR merged between them in full, not only the titles.
3. Drop internal, chore, ci, dependency and no-changelog PRs.
4. Group the rest into Features, Fixes, Performance and Breaking changes, and write one plain-language line per change in the format CHANGELOG.md already uses.
5. Open one PR that changes only CHANGELOG.md, then stop. Do not merge, tag or publish anything.
```

### Let the hourly schedule take over

The change request added this trigger to `kortix.yaml`. From now on the agent
runs every hour, on the hour, each run on its own cloud computer. It reads its
checkpoint first, so it opens a PR only when a new release has shipped. To
change the time, edit the cron line, or open **Triggers** in the workspace.

**kortix.yaml**

```yaml
triggers:
  - slug: release-notes-check
    name: Release notes check
    on:
      cron: "0 0 * * * *"
    run:
      agent: release-notes
      prompt: Load the changelog-sync skill and check owner/repo for any release published since the last checkpoint.
```

### Open a PR, a person merges

The agent writes only CHANGELOG.md, on its own branch, and opens a pull
request. It never merges, tags, publishes or announces a release. A person
edits the wording and merges.

### Review the changelog PR

Each new release gets one changelog PR. This is what a run looks like in the
session:

> **Release notes check · 15:00**
>
> Prompt: Load the changelog-sync skill and check owner/repo for any release published since the last checkpoint.
>
> Found **1** new release, v2.14.0. Read **21** merged PRs, dropped **9** as
> internal work or dependency bumps, and wrote **12** lines under Features,
> Fixes and Performance. Opened a PR against CHANGELOG.md for review.

> **The pattern**
> A **trigger** on every release spawns a session with a scoped **connector** into
> the repo. The notes playbook is encoded as **skills** and **memory**. The agent
> drafts a changelog PR and a human owns the wording and the merge.

## Make it do more

Once it works, paste any of these into the same session.

**Link each line to its PR**

```
End every changelog line with a link to the PR it came from.
```

**Draft the announcement**

```
Add a short release announcement to the changelog PR description, for a person to edit and post.
```

**Flag thin PR descriptions**

```
When a PR description is too thin to summarize, list it in the changelog PR description and mention its author so they can add one sentence.
```

## Guardrails

The agent reads the repository and writes a draft, so the access is scoped and
contained:

- **Isolation.** Every release runs in its own isolated sandbox. The session reads
  the PR history and drafts the notes; only the changelog branch is written back out.
- **Scoped secrets.** The GitHub credentials are encrypted in the secrets manager
  and injected into the sandbox at runtime, scoped to the agents you grant them to.
- **PR-gated.** The agent opens a pull request against the changelog and stops. It
  never publishes or announces the release; a human reviews the wording and merges.
- **Everything is code.** The agent's configuration, skills, and permissions are
  files in the repo, versioned and changed through a reviewed **change request**
  rather than a dashboard setting.

## The outcome

- **Every release:** Notes drafted from the PR history automatically
- **Grouped:** Changes clustered by area with internal churn dropped
- **Human review:** The agent drafts; the team owns the wording

The changelog stops falling behind, and the notes that reach review are already
grouped and readable instead of a raw list of PR titles. Reviewers edit wording
rather than reconstructing what shipped from the git history.
