Skip to Content
DocsGetting Started

Getting Started

This comprehensive guide will walk you through setting up ReleaseKit and creating your first release.

Prerequisites

Before you begin, ensure you have:

  • Linear Account - An active Linear workspace with issues
  • Linear Permissions - Admin or Owner role (for OAuth integrations and automatic labeling in Linear)
  • Platform Accounts - GitHub, GitLab, or Slack account (optional, for publishing)

Step 1: Sign In

Authenticate with Linear

  1. Visit ReleaseKit 
  2. Click Sign in in the top right, then click Sign In with Linear
  3. Authorize ReleaseKit to access your Linear workspace
  4. You’ll be redirected to your dashboard

First-Time Setup

On your first login, ReleaseKit will:

  • Create your workspace automatically
  • Set you as the workspace owner

Step 2: Create Your First Release

  1. From the dashboard, click New Release
  2. You’ll see the release creation form

Configure Your Release

Release Name (Required)

Give your release a descriptive name:

Release Name: October 2024 Release

Version Number (Optional)

Set a version number if needed:

Version: v1.2.0

Select Project or Team

Option 1: Project-Based Release Choose a Linear project to include all issues from that project:

Project: Q4 2024 Product Launch
  • The system automatically detects which team(s) the project belongs to
  • Can span multiple teams if it’s a cross-team project

Option 2: Team-Based Release (No Project) Select “No Project (Team-based release)” to create a release by team:

  • Single Team: Choose one team from the dropdown
  • Multi-Team (Business plan): Enable “Multi-Team Release” checkbox
    • Select multiple teams with checkboxes
    • “Select all teams” option available

Status

Choose the current status:

  • Planned (default) - Release is being planned
  • In Progress - Actively working on the release
  • Deployed - Release has been published

Target Date (Optional)

Set a target release date:

Target Date: 2025-10-31

Description (Optional)

Add a description for your release:

Description: Monthly feature release with bug fixes

Add Issues to Your Release

After creating the release:

  1. Click Add Issues on the release page
  2. The system automatically filters issues based on your selection:
    • Project-based: Shows only issues from that project
    • Single-team: Shows only issues from that team
    • Multi-team: Shows issues from all selected teams
  3. Search by title, ID, or description
  4. Select issues to add to the release
  5. Issues already in other releases are automatically excluded

Important: The system automatically creates a Linear label for your release:

  • Format: Release:[Name] ([Project/Team] [Version])
  • Example: Release:October 2024 (Product v1.2.0)
  • This label is automatically applied to all issues in the release

Review Changelog

ReleaseKit automatically generates a changelog from your selected issues:

  • Lists all issues with titles and Linear links
  • Uses the default template (customizable with Business plan)
  • Preview available before publishing

Step 3: Configure Publishing (One-Time Setup)

To publish releases to external platforms, configure integrations. Each user sets up their own integration credentials.

Access Configuration Menu

  1. Go to the Releases page
  2. Find any release in your list
  3. Click the three-dot menu (⋮) on the right side of the release
  4. Select Configure from the dropdown menu
  5. This opens the configuration page for that team/project combination

GitHub Integration (Pro Plan)

  1. On the configuration page, find the GitHub section
  2. Click Connect GitHub
  3. Authorize the GitHub OAuth app
  4. Select your repository from the dropdown
  5. Click Save to save the configuration

GitLab Integration (Pro Plan)

  1. On the configuration page, find the GitLab section
  2. Click Connect GitLab
  3. Authenticate with GitLab OAuth
  4. Select your project from the dropdown
  5. Click Save to save the configuration

Slack Integration (Business Plan)

  1. On the configuration page, find the Slack section
  2. Click Connect Slack
  3. Authorize Slack OAuth
  4. Select your channel from the dropdown
  5. Click Save to save the configuration

Note: Configurations are personal - each user sets up their own integration credentials for the teams/projects they work with. You need to configure each team/project combination separately.

Step 4: Publish Your Release

  1. Open your release
  2. Click Publish in the top right
  3. You’ll see the publish page

Edit Changelog (Optional)

The changelog is generated automatically, but you can:

  • Edit the markdown directly
  • Preview the HTML rendering
  • Same content is used for all platforms (auto-formatted)

Select Publishing Platforms

Choose where to publish (based on your configured integrations):

GitHub (Pro plan):

  • Select branch from dropdown
  • Release created on latest commit of that branch

GitLab (Pro plan):

  • Select branch from dropdown
  • Optionally select specific commit (default: latest)

Slack (Business plan):

  • Posts to your configured channel
  • Formatted with Slack blocks

Publish Options

Option 1: Publish to Platforms

  • Creates releases on selected platforms
  • Posts to Slack if configured
  • Marks release as “DEPLOYED”

Option 2: Mark as Published Only

  • Changes status to “DEPLOYED”
  • Does NOT post to external platforms
  • Useful for manual publishing

After Publishing

Once published:

  • Release status changes to “DEPLOYED”
  • Release is locked (can’t add/remove issues)

Step 5: View and Manage Releases

Release Dashboard

View all your releases:

  • See release dates and issue counts and progress

Release Details

Click any release to:

  • View full changelog
  • See all included issues

Quick Tips

Multi-Team Releases (Business Plan)

Create releases spanning multiple teams:

  1. Select “No Project (Team-based release)”
  2. Enable “Multi-Team Release” checkbox
  3. Select multiple teams
  4. Each team gets its own release label in Linear

Custom Changelog Templates (Business Plan)

Create reusable templates:

  1. Go to the Releases page
  2. Click the three-dot menu (⋮) on any release
  3. Select Configure
  4. Scroll to the “Changelog Template” section
  5. Edit the template using placeholders: {{release.name}}, {{release.version}}, {{issues}}, etc.
  6. Click Save to save your custom template for this team/project combination

Next Steps

Now that you’ve created your first release, explore:

Troubleshooting

Common Issues

Can’t see Linear projects?

  • Ensure you have access to projects in Linear
  • Ensure you are logged in with the correct workspace (if you have more than one). You can see ist on the dashboard in the top right.

Can’t add issues to release?

  • Check if issues already exist in another release
  • Verify the issues belong to the selected project/team
  • Ensure you have permissions in Linear

Publishing failed?

  • Verify you have a configuration for this team/project
  • Check integration credentials are valid
  • Confirm you have permissions on GitHub/GitLab/Slack
  • Review error messages on the publish page

Multi-team option disabled?

  • Multi-team releases require a Business plan
  • Upgrade in Settings

Configuration not showing?

  • Each user must configure their own integrations
  • Access via three-dot menu (⋮) on any release → Configure
  • You need at least one release to access configuration

Need Help?

IntroductionFeatures