Skip to main content

Integrating Shortcut into LinearB

Generate a Shortcut API token and connect it to LinearB to sync stories, workflows, and project data for enhanced tracking and automation.

Steven Silverstone
Updated by Steven Silverstone

A Shortcut API Token allows you to integrate Shortcut with LinearB, enabling project data to sync with Git activity for improved workflow visibility and analytics.

This guide explains how to generate an API token in Shortcut and connect it to LinearB.

Project Management connections are available only on the Enterprise tier.

Overview

  • Generate an API token in Shortcut.
  • Use the token to connect Shortcut to LinearB.
  • Enable project tracking, analytics, and Iterations insights.

Steps to Connect Shortcut into LinearB

Step 1: Log in to Shortcut

  1. Open a web browser and navigate to Shortcut.
  2. Sign in using your account credentials.

Step 2: Access API token settings

  1. Click your profile avatar in the top-right corner.
  2. Select Settings from the dropdown menu.
  3. Navigate to the API Tokens section.

Step 3: Generate an API token

  1. Click Create New API Token.
  2. Enter a descriptive name (for example, LinearB Integration).
  3. Click Generate Token.
  4. Copy the API token and store it securely. The token will not be visible again.
Treat API tokens like passwords. Do not share them publicly or store them in unsecured locations.

Step 4: Connect Shortcut to LinearB

  1. Log in to LinearB.
  2. Navigate to Company Settings > Project Management.
  3. Click Connect next to Shortcut.
  4. Paste your Shortcut API Token into the field.
  5. Click Connect to complete the setup.

After the connection succeeds, LinearB begins syncing Shortcut project data for tracking, analytics, and Iterations insights.

Branch and PR Naming Conventions

To ensure proper issue tracking, the Shortcut issue code should be included in branch and PR names.

Example:

If an issue in Shortcut is titled “Infrastructure story” with the issue code 4584, then the corresponding branch name should include the prefix "ch4584" (not case-sensitive).

Valid Branch Naming Examples:

  • ch4584-Add-repository-backfill-status

  • ch4584-Enhance-repository-status-enrichment

Each of these branches—even if created in different repositories—will be correctly matched to issue #4584 in Shortcut and reflected in Iterations view.

Matching Git Work to Shortcut Issues

LinearB’s algorithm searches for the Shortcut issue code within:

  1. Branch Names – The issue code should be included in the branch name to ensure automatic association.

  2. Pull Request (PR) Names – If the issue code is found in the PR title, the PR will be linked to the corresponding Shortcut issue.

  3. Commit Messages – If the issue code appears in commit messages, LinearB may also use this as an additional reference.

Ensuring consistent naming conventions across all repositories prevents unlinked branches and improves project tracking accuracy.

Benefits of Using Naming Conventions

  • Automatic Issue Linking – Prevents manual work in associating branches with Shortcut issues.

  • Enhanced Iterations View Tracking – Ensures that all relevant work is reflected in LinearB’s Iterations view for better visibility.

  • Better Collaboration – Helps teams quickly identify which branches and PRs relate to which issues, reducing confusion.

  • Streamlined Workflow – Ensures smooth integration between Git activity and Shortcut issue tracking.

Best Practices for Naming Branches and PRs

  • Always include the Shortcut issue code when creating a new branch.

  • If a branch name was created incorrectly, ensure the PR name contains the correct issue code before merging.

  • Maintain consistent naming conventions across all repositories.

  • Communicate these conventions to all developers to avoid inconsistencies.

Additional resources:

How did we do?

Integrating Jira Server (On-Prem) into LinearB

Project Mangement Systems Integration - Start Here

Contact