Ship code faster. Communicate better. Stop writing release notes by hand.
If you're reading this, you probably just merged a dozen PRs, your PM is asking "what shipped?", your support team has no idea what changed, and you're staring at a blank Google Doc titled "v2.4.0 Release Notes" with a blinking cursor mocking your existence.
We've been there. That's why we're building ReleaseRay.
ReleaseRay is becoming an open-source GitHub Action that runs in your own workflow. It's in active development, and there is no release yet. The first usable version will be v1.0.0. Until then, there's nothing to add to a workflow. This guide explains what the Action will do, what you'll need to run it, what it will cost, and how to follow along until it ships.
Why Another Tool?
The problem isn't writing. The problem is that you need to write the same information three different ways:
- For engineers: "Refactored authentication middleware to support OAuth2 PKCE flow"
- For your sales team: "We now support enterprise single sign-on"
- For customers: "Log in faster with your company account"
Writing this manually for every release? That's not engineering. That's data entry disguised as content marketing.
ReleaseRay is designed to do what you'd do if you had infinite time: read your PRs, understand what changed, and write release notes tailored to each audience.
Want the full case for multi-persona notes? Read Why Multi-Persona Release Notes Matter.
Step 1: What the Action Will Read
ReleaseRay will run as a step in a GitHub Actions workflow in your own repository, on your own runner. There's no service to connect and no account to create.
When you push a release tag, the Action will work out the range: from the previous SemVer tag that is an ancestor of the release tag, up to the release tag. Then it will:
- Read tags, commits, and PR numbers from the checkout
- Fetch the PR and issue content for that range from the GitHub REST API
- Classify the changes into sections you can configure
What happens under the hood
The maintainer runs no service. Nothing is sent anywhere except to GitHub and to the LLM provider you configure. Your release notes are generated inside your own workflow run.
That's the raw material for your release notes.
Step 2: How the Range Is Defined
Release notes need boundaries. ReleaseRay will use the tags you already create.
By tags — the range runs from the previous SemVer tag that is an ancestor of your release tag to the release tag itself. Tag v2.4.0, and the notes will cover everything merged since v2.3.0.
You won't pick ranges by hand or in a separate tool. If you tag your releases, the range follows from your Git history.
Step 3: Notes for Each Persona
For each release, ReleaseRay will write notes for three default personas: Engineer, Internal, and Customer. You'll be able to adjust personas, sections, tone, and instructions in .releaseray/config.yml, and override prompts in .releaseray/prompts/*.md. You won't need a config file to use the defaults.
The examples below show the kind of output each persona is meant to produce.
Engineer Persona
Style: Technical, detailed, upgrade-focused
Example Output:
Features
- Added OAuth2 PKCE support (#245)
- Implemented Redis session store with connection pooling (#248)
Bug Fixes
- Fixed race condition in webhook processor (#251)
Breaking Changes
AuthService.login()now returnsPromise<Session>instead ofUserUpgrade Instructions: See migration guide in PR #245.
Who reads this: Your engineering team, open-source contributors, technical integration partners.
Internal/CSM Persona
Style: Customer-impact focused, talking points for Sales/Support
Example Output:
Highlights
Enterprise SSO is Live. Customers can now log in with company credentials (Google Workspace, Okta, Azure AD).
Talking points: Faster onboarding, better security, compliance-friendly. New "Log in with SSO" button in Settings.
Who reads this: CSMs prepping for customer calls, sales reps, support agents.
Internal notes will never go to public surfaces by default.
Customer Persona
Style: Benefit-driven, jargon-free, friendly
Example Output:
What's New
Log in with your company account. Use your work email to sign in. No more remembering another password.
Faster performance. Pages load 40% quicker. Bug fixes. Resolved chart loading on Safari and email notification issues.
Who reads this: End users and customers who clicked "What's new?"
Step 4: Where the Notes Will Go
ReleaseRay generates drafts, not gospel. You're still the human in the loop.
Outputs
The Action is designed to publish to:
- The GitHub Release body for the tag
CHANGELOG.mdin your repository- The job summary of the workflow run
- Workspace files: one Markdown file per persona, plus
notes.json, so later steps in your workflow can use them
Slack, Microsoft Teams, and Intercom outputs are planned for v1.1.
Editing and re-runs
Edit the notes wherever they land. If you re-run the workflow, ReleaseRay won't duplicate notes, won't make an LLM call when nothing has changed, and will keep your edits.
What You'll Need
- A GitHub repository that tags releases with SemVer tags
- GitHub Actions enabled for that repository
- An LLM API key for one of the supported providers: OpenAI or an OpenAI-compatible endpoint, or AWS Bedrock. An Anthropic adapter is planned for v1.1.
What It Will Cost
ReleaseRay itself is free and open source under the MIT license. You'll pay two things, both directly to the provider:
- Your LLM provider, for the calls made with your key
- GitHub Actions minutes, on private repositories only. Public repositories get Actions minutes free.
Tips for Better Notes
1. Use PR Labels
Add labels like type: feature, type: bug, type: breaking, area: auth. They give ReleaseRay more context when it classifies changes.
2. Write Good PR Titles
Bad: "fix stuff" Good: "Fix race condition in webhook processor causing duplicate events"
3. Link Issues
Use "closes #123" in your PR body. ReleaseRay will read the issue content for better notes.
Common Questions
- "Can I use it today?" Not yet. There's no release until
v1.0.0. - "Do I need to write PRs differently?" No. Decent titles and linked issues are enough.
- "What if I don't use Git tags?" The range is defined by SemVer tags, so you'll need to tag releases.
- "Can I edit after publishing?" Yes. Re-runs keep your edits.
- "Will my code or PR data go to ReleaseRay?" No. The maintainer runs no service. Data goes only to GitHub and to the LLM provider you configure.
- "GitLab / Bitbucket?" GitHub only for now.
What's Next?
Level up your release workflow:
- Setting up persona-specific outputs: Why Multi-Persona Release Notes Matter
- Automating your branch promotions: Automate Branch Promotions with GitHub Actions
- Enforcing semantic versioning: Free AI Assistant Rules for SemVer
To follow development and watch for the first release, star the repository on GitHub.
Get Started Today
Free and open source. You bring your own LLM key. Questions or ideas? Open an issue on GitHub Issues or read the documentation.
Written by Cristobal Mitchell, founder of ReleaseRay.
Cristobal Mitchell
Founder of ReleaseRay
Building ReleaseRay — automated release notes from GitHub PRs for developers, PMs, and customers.
Related Posts
Release Notes Best Practices: The Complete Guide for Engineering Teams (2026)
How to write release notes that actually get read. Audience awareness, formatting standards, and automation without the team burnout. The definitive guide for engineering teams.
Why Multi-Persona Release Notes Matter
Learn why engineering teams need different release notes for developers, PMs, and customers, and how to create them without writing three versions manually.
Automate Branch Promotions with GitHub Actions
Free GitHub Actions templates to automate release workflows: auto-create staging and production PRs with semantic version prediction. Stop manual branch promotions and version bumping.
ReleaseRay is an open-source GitHub Action. The first release is on its way.