Integrating Jira Cloud into LinearB (OAuth 2.0)

LinearB integrates with Jira Cloud using OAuth 2.0 so it can sync Jira projects, boards, issues, and incidents and correlate them with Git activity. This enables better visibility into project progress, task completion, and developer productivity.

To complete this setup, the user who authorizes Jira must have the required Jira permissions, and you must have a LinearB Admin role.

---

Overview

• Connect Jira Cloud to LinearB using OAuth 2.0 (required for Jira Cloud).
• Authorize LinearB in Jira and return to LinearB to complete validation.
• Upgrade from the legacy OAuth 1.0 integration to OAuth 2.0 without losing data.
• Use Reauthorize if the connection fails or if you need to switch the Jira user.

Prerequisites

Before connecting, confirm the Jira user who performs the authorization has:

• Read and write permissions for all relevant Jira projects.
• Permission to authorize third-party applications in Jira Cloud.

If the user does not have adequate permissions, the connection may fail and require re-authorization using a different Jira user.

---

Steps to Connect Jira Cloud with LinearB

Step 1: Start the Jira Cloud connection in LinearB

1. In LinearB, go to Settings → Project Management → Projects.
2. Choose Jira as the management tool and click Connect.
3. Under Connect Jira, select Jira Cloud.
4. Click Connect to Jira to begin the OAuth 2.0 authorization flow.

If your Jira deployment is hosted on-premises, see the Jira Server (On-Prem) Connection Guide .

 

Step 2: Authorize LinearB in Jira Cloud

1. You’ll be redirected to Jira Cloud (log in if prompted).
2. Review the permissions LinearB is requesting.

3. Click Allow to grant access.

    

After you approve access, Jira redirects you back to LinearB automatically.

 

Step 3: Complete validation and activate the integration

After Jira redirects you back to LinearB, LinearB runs validation checks. This may take a few minutes.

• Authorization Code
• Token Exchange
• Access Check
• Permissions

1. Wait until all validations pass.
2. Click Continue to activate the integration.

Once activated, LinearB begins syncing Jira Cloud data (projects, boards, issues, and incidents) and correlating it with Git activity.

---

Upgrading from OAuth 1.0 to OAuth 2.0

If your LinearB workspace is still using the legacy OAuth 1.0 Jira integration, you’ll see an upgrade banner on the Jira settings page. Upgrading does not remove your existing settings. After authorization succeeds, LinearB continues syncing Jira data under OAuth 2.0.

1. Go to Settings → Project Management → Projects.
2. Under Jira, find the upgrade banner.
3. Click Authorize Jira.
4. You’ll be redirected to Jira to approve the new OAuth 2.0 authorization.
5. After allowing access, you’ll return to LinearB where the integration completes validation.

 

Result: Your existing Jira settings remain in place, and LinearB continues syncing your Jira projects, boards, and issues under OAuth 2.0.

---

Branch and PR Naming Conventions

To enable Iterations to recognize and match Git work to Jira issues, the Jira issue key (for example, PROJ-123) must be present in branch names and pull requests (PRs).

Recommended Format: <Jira-issue-key>-<descriptive-title>

Example Naming Conventions

For pull requests (PRs), the Jira issue key should also be included.

Example PR Title: Add repository backfill status (LINB-397)

---

How Iterations Matches Git Work to Jira Issues

Iterations automatically scans Git branches, PR titles, and commits for Jira issue keys. The matching algorithm follows these rules:

1. Branch Names

   If the branch name includes a valid Jira issue key, Iterations automatically associates it with the correct Jira issue.

2. Pull Request (PR) Titles

   If the PR title contains the Jira issue key, Iterations matches the PR to the issue—even if the branch name does not follow the convention.

3. Commit Messages

   Including the Jira issue key in commit messages adds an additional reference for tracking but is not required.

Example Matching Scenario

Jira Issue: Repository selection - backfill and statuses

Jira Issue Key: LINB-397

Matching Branch Names:

• LINB-397-add-repository-backfill-status
• LINB-397-repository-status-enrichment

Both of these branches, even when they are in different repositories, are linked to LINB-397 in Iterations.

Handling Issues with Subtasks

If a parent Jira issue has multiple subtasks, Iterations associates branches and PRs with either:

• The parent issue key
• The subtask issue keys

Example:

Parent Jira Issue: Improve Dockerfiles for better layering

• Parent Issue Key: LINB-603
• Subtasks:
  • LINB-775 (Optimize Docker image size)
  • LINB-776 (Improve build caching)

Branch Matching Rules for Subtasks

Iterations matches both the parent and subtask issue keys to the parent Jira issue in the Iterations view.

---

Benefits of Using Naming Conventions

• Automatic Issue Linking – No need for manual tracking in Iterations.
• Improved Iterations Tracking – Ensures all relevant work is reflected in LinearB’s Iterations view.
• Better Collaboration – Teams can quickly identify which Git branches and PRs relate to specific Jira issues.
• Consistent Workflow – Standardized naming reduces confusion and enforces best practices across repositories.

Best Practices

• Always include the Jira issue key when creating a branch.
• Use clear, descriptive titles to specify the task being worked on.
• Ensure the PR title contains the Jira issue key if the branch name does not follow conventions.
• Maintain consistency across teams and repositories.
• Educate developers on the importance of naming conventions to ensure Iterations tracks work accurately.

---

Reauthorization and troubleshooting

If the initial authorization fails, or if you need to connect using a different Jira user, click Reauthorize from the Jira connection panel.

Common reasons the connection fails:

• The Jira user does not have the required permissions.
• Multiple Jira sites are detected and the wrong site was selected.
• Incorrect credentials or the wrong Jira Cloud account was used.

Even after a successful connection, the Reauthorize option remains available so you can switch Jira users at any time. If re-authorization fails, the Jira integration remains in a failed state until corrected.

---

Benefits of connecting Jira Cloud to LinearB

• Sync Jira data (projects, boards, issues, and incidents) and correlate it with Git activity.
• Improve visibility into project progress and task execution.
• Reduce setup issues with built-in validation checks.
• Maintain continuity when upgrading from OAuth 1.0 to OAuth 2.0 without losing existing data.