Getting Started with ReleaseRay

Time to first release notes: ~5 minutes ⚡

ReleaseRay transforms your merged PRs into polished, multi-persona release notes. This guide walks you through installation, configuration, and publishing your first release—no technical expertise required.

Prerequisites

Before you begin, make sure you have:

• ✅ A GitHub account with admin access to at least one repository
• ✅ Repositories with merged pull requests (your release note content!)
• ✅ (Optional) Semantic version tags (v1.0.0, v1.2.3, etc.) for tag-based release ranges

Don't have repos set up yet? No problem! You can install ReleaseRay now and it'll be ready when you do.

Step 1: Install the GitHub App

Install from GitHub Marketplace

1. Visit github.com/apps/releaseray
2. Click "Install"
3. Choose "All repositories" or "Select repositories"
4. Select the repos you want ReleaseRay to access
5. Click "Install & Authorize"

You'll be redirected to the ReleaseRay dashboard automatically.

Understanding Permissions

ReleaseRay requests these permissions:

Why write access? To enable the optional CHANGELOG.md publisher. Don't want it? No problem—all other publishers work without writing to your repo.

We never:

• ❌ Read your source code
• ❌ Modify files except CHANGELOG.md (only when you select it)
• ❌ Create releases without your explicit action
• ❌ Access data from unselected repositories

Step 2: Connect Your Organization

After installation, you'll land on the onboarding flow:

2.1 Create Your Organization

Organization Name: [Your Company]
Slug: your-company (for your hosted changelog: releaseray.com/changelog/your-company)

Your slug is permanent—choose wisely! Use lowercase and hyphens.

2.2 Select Your First Repository

Choose a repository to start with. You can add more later.

Pro tip: Start with your most active repo—it'll have plenty of PRs for great release notes!

2.3 Set Release Preferences

Configure how ReleaseRay should handle this repo:

Release Range:

• ✅ Tag-based (recommended): Define a range using two version tags (e.g., v1.1.0 → v1.2.0)
• ⚪ Date-based: Define a range by start and end dates
• ⚪ PR-based: Define a range by specific PR numbers

Default Personas:

• ✅ Engineer (technical details)
• ✅ Internal/CSM (customer impact)
• ✅ Customer (plain language)

Publishing Channels: (can change anytime in Settings → Publishing)

• ✅ GitHub Releases (no setup needed)
• ✅ Hosted Changelog (no setup needed)
• ✅ CHANGELOG.md (no setup needed)
• ✅ releases.md (no setup needed)
• ⚪ Slack (requires integration setup)
• ⚪ Teams (requires integration setup)
• ⚪ Intercom (requires integration setup - Team plan+)
• ⚪ Email (requires integration setup - Team plan+)

Click "Complete Setup" and you're ready!

Step 3: Generate Your First Draft

1. Go to Dashboard → Releases
2. Click "Generate New Draft"
3. Define your release range using one of three methods:

Option A: Tag-Based (most common)

From: v1.1.0
To:   v1.2.0

Works best if your repo uses semantic version tags. ReleaseRay fetches all merged PRs between those two tags.

Option B: Date-Based

From: 2024-01-01
To:   2024-01-31

Useful for weekly or sprint-cadence teams that don't tag every release.

Option C: PR-Based

PRs: #201, #202, #204, #209

Useful when you want to hand-pick exactly which PRs appear in a release, regardless of when they merged.

4. Click "Generate Drafts"
5. Wait ~30-90 seconds depending on PR count

What's happening behind the scenes:

• 🔍 ReleaseRay fetches all merged PRs in the range
• 🤖 AI analyzes changes and groups them by type
• ✍️ Three persona-specific versions are generated
• ✅ Drafts are ready for review!

Step 4: Review & Edit Your Drafts

Persona Tabs

Switch between personas to see how ReleaseRay adapted the content:

🔧 Engineer Tab:

• Technical details
• PR numbers (#123, #456)
• Breaking changes highlighted
• Upgrade instructions

👔 Internal/CSM Tab:

• Customer impact language
• No PR numbers
• Talking points for support
• Professional tone

💙 Customer Tab:

• Plain language
• Benefit-driven
• No jargon
• Friendly, conversational

Inline Editing

Each draft is fully editable—click to edit any section:

• Reorder changes: Drag and drop
• Edit text: Click and type
• Add sections: Click "+" between sections
• Delete items: Click trash icon

Pro tip: Use AI as a starting point, then fine-tune to perfection!

Step 5: Publish Everywhere

Select Channels

Click "Publish" and choose where to publish. Each channel can be assigned a different persona — for example, the Engineer draft to GitHub Releases and the Customer draft to Slack and Email.

Configure Publishing Options

GitHub Releases:

• ✅ Create release
• ✅ Set as latest release
• ⚪ Mark as pre-release (for betas)

Slack/Teams:

The message goes to whichever channel your webhook is configured for in Settings → Integrations. Change the target channel by updating your webhook there.

Click "Publish Now"

Your release notes are now live across all selected channels! 🎉

What's Next?

Configure Integrations

Unlock the full power of ReleaseRay:

1. Set up Slack integration - Notify your team automatically
2. Connect Microsoft Teams - Share with sales/support
3. Add Intercom integration - Publish to Help Center (Team plan)

Customize Personas

Make release notes perfect for your audience:

1. Learn about personas - Understand default personas
2. Create custom personas - Tailor for your industry
3. Persona override - One-off customizations

Automate Your Workflow

Set it and forget it:

1. Set up webhooks - Trigger draft generation from your CI/CD pipeline
2. Configure release cadence - Weekly, bi-weekly, or on-demand
3. Enable auto-publish - Skip review step for trusted channels

Add More Repositories

Scale to your entire organization:

1. Go to Settings → Repositories
2. Click "Add Repository"
3. Select from your installed repos
4. Configure preferences
5. Start generating!

Common Workflows

Workflow 1: Weekly Release Cadence (Tag-Based)

Perfect for: SaaS products with weekly releases and semantic version tags

1. Monday: Merge PRs throughout the week
2. Friday: Create tag `v1.23.0` in your repo
3. Dashboard: Generate New Draft → From: v1.22.0, To: v1.23.0
4. Review: PM reviews Customer persona
5. Publish: One click to GitHub + Slack + Intercom

Workflow 2: Sprint Cadence (Date-Based)

Perfect for: Teams in beta/early stage or who don't tag every release

1. Merge features throughout the sprint
2. End of sprint: Generate New Draft → date range for the last 2 weeks
3. Generate drafts
4. Team review before publishing

Workflow 3: Curated Releases (PR-Based)

Perfect for: Teams shipping multiple PRs but wanting precise control over what surfaces in a given release

1. Ship PRs continuously throughout the week
2. At release time: open "New Release Range" → By PRs tab
3. Enter the PR number range for this release
4. Generate drafts from exactly those PRs
5. Publish to GitHub Releases + Hosted Changelog + Email subscribers

Troubleshooting

"No Pull Requests Found"

Cause: No merged PRs in the selected range

Fix:

1. Check your range definition—are there merged PRs within those bounds?
2. Try expanding the range (e.g., go back one more tag, widen the date window, or add more PR numbers)
3. Ensure PRs were merged (not closed without merging)

"Draft Generation Taking Too Long"

Normal: 30-60 seconds for most repos
Longer (2-3 min): Large repos with 50+ PRs in range

If stuck >5 minutes:

1. Refresh the page
2. Check Settings → Jobs to see status
3. Contact support if stuck

"Permission Denied When Publishing"

GitHub Releases: Ensure ReleaseRay has Contents: Write permission
Slack/Teams: Check webhook URL is correct
Intercom: Verify API key has write access

Fix: Go to Settings → Integrations and click "Test Connection"

"Release Notes Look Too Technical/Too Simple"

Solution: Switch personas or create a custom one!

1. Too technical for customers? Use Customer persona
2. Too simple for engineers? Use Engineer persona
3. Need something specific? Create custom persona

Tips for Great Release Notes

1. Use Semantic Version Tags

Why: Tag-based ranges are the easiest way to define a release and produce clean changelogs

✅ Good: v1.2.0, v1.2.1, v1.3.0
❌ Bad: release-2024-01-15, prod-deploy

2. Write Descriptive PR Titles

Why: PR titles become the basis for release note entries

✅ Good: "Add OAuth2 authentication for GitHub and GitLab"
❌ Bad: "Auth update" or "Fix"

3. Use Conventional Commits

Why: Helps ReleaseRay categorize changes automatically

✅ feat: Add dark mode toggle
✅ fix: Resolve race condition in draft generation
✅ docs: Update API documentation

4. Link Issues in PR Descriptions

Why: ReleaseRay uses issue context to improve release notes

Closes #123
Fixes #456
Relates to #789

5. Review Before Publishing to Customers

Why: AI is great but not perfect—catch errors before customers do

• Verify breaking changes are clearly marked
• Check for typos or awkward phrasing
• Ensure sensitive info isn't exposed

Keyboard Shortcuts

Speed up your workflow with these shortcuts:

Get Help

Documentation

• 📖 Dashboard Guide - Master the UI
• 🎭 Personas Guide - Customize for your audience
• 🔗 Integrations - Connect Slack, Teams, Intercom
• 🪝 Webhooks - Automate everything
• 🔧 API Reference - Programmatic access

Support

• 💬 Live Chat - Bottom right corner (9am-5pm PT)
• 📧 Email - support@releaseray.com
• 🐛 Bug Reports - GitHub Issues
• 💡 Feature Requests - Feedback Board

Community

• 🐦 Twitter - @ReleaseRayHQ
• 📰 Blog - releaseray.com/blog

You're all set! Ready to ship great release notes? Open your dashboard →

Quick links:

• Configure integrations
• Customize personas
• Set up webhooks
• Invite your team