getting-startedtutorialrelease-notes

Getting Started with ReleaseRay

Cristobal MitchellFounder of ReleaseRay··Updated November 19, 2026·6 min read
Share:

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 returns Promise<Session> instead of User

Upgrade 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.md in 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"

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:

  1. Setting up persona-specific outputs: Why Multi-Persona Release Notes Matter
  2. Automating your branch promotions: Automate Branch Promotions with GitHub Actions
  3. 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

Get started →

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.

C

Cristobal Mitchell

Founder of ReleaseRay

Building ReleaseRay — automated release notes from GitHub PRs for developers, PMs, and customers.

ReleaseRay is an open-source GitHub Action. The first release is on its way.

We value your privacy

We use cookies to enhance your experience. Essential cookies are required for the site to function. You can choose to accept all cookies or manage your preferences.