Release notes writer
By Toolspoke
Reads the pull requests merged since your last release and the Linear issues they close, and drafts customer-facing release notes in Notion.
Needs a Toolspoke account. You choose which project it installs into.
- GitHub + Linear + Notion
- Required integrations
- Runs when you ask
- No schedule of its own
- Create the draft
- What its last step does
- Nothing destructive
- 0 of 54 actions in its tools
On this page
The short version
- What it is
- A ready-made Toolspoke agent that turns what your team merged into release notes a customer would want to read.
- What it reads
- Pull requests merged into your release branch since the last notes, and the Linear issues they close.
- What you get
- A Notion draft grouped into New, Improved and Fixed, with every line linked to its pull requests.
- What it leaves out
- Chores, refactors, tests, CI, dependency bumps and reverts, listed at the end so you can put one back.
- How often
- When you ask. It has no schedule of its own.
- What it never does
- Publish the notes, create a release or tag, or name a customer, colleague or security detail in a line.
- What you need
- A Toolspoke account, GitHub, Linear and a Notion database for the notes.
What Release notes writer does
Release notes writer is an AI agent that reads the pull requests merged since your last release, and the Linear issues they close, and drafts release notes in Notion in words a customer would use. A person edits and publishes them.
Release notes are the last job before a release and the first one to slip. Someone scrolls through a list of merged pull requests titled "fix: tz edge case" and "refactor scheduler", and tries to remember which ones a customer would notice.
A generated changelog is fast and unreadable. It lists every commit, including the ones that only matter to the team, in the team's own shorthand.
Release notes writer reads each pull request and the issue behind it, leaves out what customers never see, and writes what changed and why it matters in plain sentences. Each line keeps its pull request links in a note for the editor, so checking it takes a click.
In practice, before each release you have a draft with:
- New, Improved and Fixed, each line written for a customer
- Breaking changes and migrations flagged at the top, before you publish
- Lines it was unsure of, marked Check, as questions for you
- The internal pull requests it left out, listed so you can put one back
How it works
Release notes writer works in four steps each time you ask: it finds what was merged, reads each change, sorts out what customers see and writes the draft. All of it comes from the agent's written instructions, which you can read and edit after you install it.
Step 1: Find what was merged
Pull requests merged into your release branch since the last notes.
Step 2: Read the why
The Linear issues each pull request closes, for the customer's problem.
Step 3: Leave out the internals
Chores, tests, CI, dependency bumps and reverts.
Step 4: Write the draft
New, Improved and Fixed, with links, as a Draft page.
It picks up where the last notes ended
Each draft records the date it covers to. Ask for notes since the last notes and it starts from there, so nothing is covered twice or skipped. You can also give it a date or a pull request to start from.
It writes for customers, not engineers
Each line says what changed and why it matters, in the present tense: you can now export a report as CSV. No internal names, file paths, ticket numbers or people's names. Several pull requests for one feature become one line.
It asks rather than guesses
When a pull request does not say what changed for a user, the agent does not read the code and guess. It writes the line as a question for the editor and marks it Check.
It flags what needs care
A breaking change, a migration, a removed feature or a changed default goes at the top under Before you publish, with its pull request. The limits are listed under what it will never do.
What a draft looks like
A run of Release notes writer creates one Draft page in Notion. It opens with anything that needs care, then the notes in three groups, then what it left out.
Release notes, 6 to 19 October
23 pull requests merged into main. 13 lines in the notes, 1 to check, 10 left out as internal.
Before you publish (1)
- Changed default: new projects now keep reports for 90 days instead of forever. Existing projects are not affected. (#407)
The notes (13)
- New: You can now export any report as a CSV file. (#412, #414)
- Improved: Dashboards load about twice as fast on large projects. (#405)
- Fixed: Scheduled emails now go out at the right time for teams outside UTC. (#409)
- Check: #398 changes the invite flow. What does a user see differently?
Left out (10)
Dependency bumps (4), test and CI changes (3), a refactor of the scheduler, and a revert with the change it reverted.
- Before you publish
Breaking changes, migrations, removed features and changed defaults. Read these first: they may need more than a line.
- The notes
New, Improved and Fixed, written for customers, each with its pull request links for the editor. Lines marked Check are questions the agent could not answer from the pull request.
- Left out
Pull requests it judged internal, one line each, so you can put one back if a customer would notice it.
When the window is busy
GitHub returns at most 100 pull requests per request. If a window holds more, the draft says some may be missing and how many were read, rather than presenting part of the release as all of it.
If nothing customer-facing was merged, it says so and creates no page.
Who uses Release notes writer
Release notes writer suits any team that ships often and wants customers to know what changed, without an evening of writing each time. The examples use made-up names.
A product manager who owns the changelog
Sofia Romero used to spend Friday afternoon turning pull request titles into sentences. Now she edits a draft and publishes it.
An engineering lead shipping weekly
Daniel Kim asks for notes since the last notes before each release, and checks the Before you publish section first.
A support lead answering what changed
Grace Liu reads the Fixed group to tell customers their bug is gone, and links them to the published notes.
A founder writing the monthly update
Tunde Bakare asks for the whole month and uses the New group as the product section of his investor update.
What Release notes writer connects to
Release notes writer connects to three tools: it reads GitHub and Linear, and reads and writes your Notion release notes database. You connect each one yourself, and Toolspoke stores the connection encrypted, so the agent never sees the credential.
GitHub
RequiredManage repositories, issues, pull requests, and Actions.
Authentication: Personal access token
Linear
RequiredCreate, update, and search issues across your teams.
Authentication: API key
Notion
RequiredRead and update pages, databases, and team knowledge.
Authentication: Notion OAuth
| Tool | What Release notes writer does | What it cannot do |
|---|---|---|
| GitHub | Lists and reads merged pull requests (list_pull_requests, get_pull_request). | Publish anything to your users. The connector can create issues, branches and commits and comment on pull requests, and the agent is told to do none of that. |
| Linear | Reads the issues a pull request closes (get_issue). | Reach teams the connection cannot see. It can create and update issues, and the agent is told not to. |
| Notion | Finds the last notes and creates a Draft page (notion-fetch, notion-query-data-sources, notion-create-pages). | Reach pages you have not shared with it. It can edit pages it can reach, and the agent is told never to change an earlier release notes page. |
That the agent only reads GitHub and Linear, and only creates a draft in Notion, is an instruction to the agent, not a lock. If you want a lock, a project can switch individual actions off: GitHub's create, update, comment and workflow actions, Linear's create and update actions, and Notion's update and move actions. The access control guide explains how.
None of the three tools publishes to your users. The notes reach customers only when a person copies them to your changelog, blog or email.
What Release notes writer will never do
Release notes writer is told never to publish the notes, never to create a release, tag, branch or commit, and never to write about something that is not merged. It drafts, and a person publishes.
- Publish, post or send the notes anywhere.
- Create a release, a tag, a branch, a commit or an issue, or comment on a pull request or issue.
- Write about something that is not merged, or promise what is coming next.
- Name a customer, an employee or a security issue's details in a line.
- Change or delete an earlier release notes page.
Why it will not publish
Release notes are a promise to customers about what changed. A person reads the draft, fixes the lines marked Check and decides when it goes out.
Why it keeps internals out
A release note that names a colleague, a customer, a file path or the detail of a security fix tells the wrong people the wrong things. The agent writes what changed for the user and keeps the links in a note for the editor.
Why it will not guess
When a pull request does not say what changed for a user, a guess from the code reads as fact. The agent asks instead, and marks the line Check.
If something goes wrong
If GitHub cannot be read, say so and stop. If Linear cannot be read, write from the pull requests alone and say that issue context is missing. If Notion cannot be written, give the draft in the reply so the work is not lost. If nothing customer-facing was merged in the window, say so and create no page.
These are written into Release notes writer's instructions. They guide the agent, but they are not a permission. What it is allowed to touch is set by the access you grant.
Release notes writer reads what was merged and drafts the notes. What goes out to customers, and when, stays with a person.
When Release notes writer runs
Release notes writer has no schedule. It runs when you ask for notes, and it stops when the draft is written.
- You ask for notes, since the last notes, a date or a pull request.
- It reads what was merged and the issues behind it.
- It creates one Draft page in Notion and gives you the link.
- It publishes nothing, anywhere.
Each run uses model credit from your workspace balance. A release with more pull requests costs more, because there is more to read. The GitHub, Linear and Notion calls themselves are free.
Your copy is an ordinary agent in your project. You can run it on demand, give it a schedule such as every second Friday to match your release cycle, and edit its instructions. The agent's page lists recent runs and their cost.
How to set up Release notes writer
To start drafting release notes, add Release notes writer to a Toolspoke project, connect GitHub, Linear and Notion, and ask for your first draft. It takes a few minutes.
Step 1: Create a Toolspoke account or sign in
Choose Use this agent. If you are new, you will be asked to sign up first, and you come straight back to this agent afterwards.
Step 2: Add it to a project
Pick the project it should live in. You get your own editable copy, and you can see the three tools it brings before anything connects.
Step 3: Connect GitHub and Linear
Sign in to GitHub and choose the repositories and the release branch. Sign in to Linear and choose the teams whose issues those repositories close.
Step 4: Make the notes database
In Notion, create a database with a Status property that has a Draft option and a Covers to date property, and share it with the connection.
Step 5: Ask for your first draft
Ask for notes for the last two weeks. Read the draft, check the lines marked Check, and see what it left out.
Make Release notes writer fit your team
Release notes writer's instructions are plain English and you can edit them after you install it. Installing copies the agent, so your edits stay with your copy. Open the agent in Toolspoke and tell the builder what to change, and it rewrites the instructions.
Paste any sentence below into the builder chat, or say the same thing in your own words.
Write in a friendly tone, address the reader as you, and start each New line with a verb.
Leave out any pull request labelled skip-notes, and put any labelled highlight first in New.
Group lines by the Linear project of their issue, then by New, Improved and Fixed.
Also add a second section for the team, with every pull request including the internal ones, one line each.
Run every second Friday at 2 PM, for notes since the last notes.
This gives the agent a schedule, so the builder edits its schedule as well as the instructions.
None of these edits needs more access or touches the Never rules. They change what Release notes writer is told, not what the connections allow.
How it compares to other options
Release notes writer beats the alternatives when you want notes customers can read, drafted from what really shipped, and loses to them when you need notes published automatically on every release.
| Compared on | Release notes writer | A changelog generator | Writing them by hand | No release notes |
|---|---|---|---|---|
| Readable by customers | Yes | Commit messages | Yes | Nothing to read |
| Covers everything merged | Yes, with what it left out | Yes | What you remember | No |
| Keeps internals out | Yes, by its rules | Only with strict labels | Yes | Not applicable |
| Flags breaking changes | Yes, at the top | With conventional commits | If you notice | No |
| Publishes automatically | No, a person does | Yes | No | No |
| Time per release | Minutes to edit | None | An hour or more | None |
A changelog generator is the better choice for a library whose users read commit messages. Release notes writer is for a product whose customers want to know what they can now do.
Writing notes by hand gives the best writing, and the agent's draft is where that writing starts, with everything that was merged already in front of you.
Frequently asked questions
Will Release notes writer publish my notes?
No. It creates a Draft page in Notion. None of its tools publishes to your users, and a person copies the notes to your changelog, blog or email.
How does it know what customers see?
It leaves out pull requests labelled internal, chore, refactor, test, ci, docs or dependencies, ones that only change tests or build files, and reverts. It lists what it left out, so you can put one back.
Does it need Linear?
It works best with it, because the issue usually says what the customer's problem was. Without Linear it writes from the pull requests alone and says so.
What about security fixes?
It writes Fixed a security issue and puts the detail in the editor's note, never in the line itself.
Can it cover several repositories?
Yes. Choose them at install, and it reads each one for the same window and writes one set of notes.
Does it work with Jira or GitLab?
Not as shipped, because it reads GitHub and Linear. Toolspoke has Jira and GitLab toolkits, so you can ask the agent builder for another version. It needs its own instructions.
Is Release notes writer free?
It has no price of its own, and every Toolspoke plan includes agents. Tool calls cost nothing, but each run draws on your usage balance. Pricing has the details.
Ship the notes with the release
Connect GitHub, Linear and Notion and ask for your first draft. It is ready to edit in minutes.