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 automatic range detection

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 Detection:

• ✅ Automatic (recommended): ReleaseRay watches for new tags
• ⚪ Manual: You trigger draft generation manually

Default Personas:

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

Publishing Channels: (can change later)

• ✅ GitHub Releases
• ✅ Hosted Changelog
• ⚪ Slack (requires integration setup)
• ⚪ Teams (requires integration setup)
• ⚪ Intercom (requires integration setup - Team plan+)

Click "Complete Setup" and you're ready!

Step 3: Generate Your First Draft

Option A: Automatic (Tag-Based)

If your repo uses semantic version tags:

1. Create a new tag in your repo:

   git tag -a v1.2.0 -m "Release v1.2.0"
   git push origin v1.2.0
   

2. ReleaseRay detects the tag and starts generating drafts automatically

3. Check your dashboard in ~60 seconds—your drafts are ready!

Option B: Manual Generation

If you don't use tags or want full control:

1. Go to Dashboard → Releases
2. Click "Generate New Draft"
3. Configure your release range:

From: v1.1.0 (previous release tag)
To: HEAD (latest commit)

OR

From: [commit SHA]
To: [commit SHA]

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!

Request Approval (Optional)

Need sign-off before publishing?

1. Click "Request Approval"
2. Select approvers from your team
3. Add a note: "Please review before I publish to customers"
4. Approvers get notified and can approve/reject

Step 5: Publish Everywhere

Select Channels

Click "Publish" and choose where to publish:

Configure Publishing Options

GitHub Releases:

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

Hosted Changelog:

• ✅ Publish to public changelog
• ⚪ Featured release (shows on homepage)

Slack/Teams:

• Channel: #releases (dropdown)
• Mention: @channel or specific users

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 - Auto-generate on every tag
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

Perfect for: SaaS products with weekly releases

1. Monday: Merge PRs throughout the week
2. Friday: Create tag `v1.23.0`
3. Auto: ReleaseRay generates drafts
4. Review: PM reviews Customer persona
5. Publish: One click to GitHub + Slack + Intercom

Workflow 2: Manual Control (Pre-Production)

Perfect for: Teams in beta/early stage

1. Merge features to develop branch
2. When ready to release: Manual trigger
3. Select commit range manually
4. Generate drafts
5. Team review before publishing

Workflow 3: High-Frequency Shipping

Perfect for: Teams shipping multiple times per day

1. Auto-generate on every tag
2. Skip approval step
3. Auto-publish to GitHub Releases + Hosted Changelog
4. Weekly digest sent to customers (consolidates all releases)

Troubleshooting

"No Pull Requests Found"

Cause: No merged PRs in the selected range

Fix:

1. Check your tag range—are there merged PRs between those commits?
2. Try expanding the range (e.g., go back one more tag)
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: ReleaseRay auto-detects ranges and generates better 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

• 🗣️ Discord - Join 500+ ReleaseRay users
• 🐦 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