Connect Azure Boards to LinearB (OAuth 2.0 or PAT)

Overview

Connect Azure Boards to LinearB to track work items, iterations, and engineering delivery alongside your Git activity.

LinearB supports two authentication methods for Azure Boards: OAuth 2.0 (recommended) and Personal Access Token (PAT).

Choose an Authentication Method

Capability	OAuth 2.0 (Recommended)	Personal Access Token (PAT)
Authentication	Sign in with a Microsoft account associated with your Microsoft Entra organization.	Generate a PAT in Azure DevOps and enter it in LinearB.
Expiration	Access tokens are refreshed automatically. No manual token renewal is normally required.	The token expires on the configured date and must be renewed manually.
Organization selection	Select an Azure DevOps organization associated with your authenticated account.	Enter the Azure DevOps organization manually.
Permissions	Read-only access to user profile information, projects and teams, and work items.	Read access to User Profile, Project and Team, and Work Items.
Supported environments	Azure DevOps Services (cloud).	Azure DevOps Services (cloud) and Azure DevOps Server (self-hosted).

---

Before You Begin

• Subscription: Project Management integrations are available with the LinearB Enterprise plan.
• LinearB permissions: You must be a LinearB admin to connect or reauthorize an Azure Boards integration.
• Azure DevOps access: Your account must have access to the Azure DevOps organization and permission to view the projects and work items you want LinearB to analyze.
• OAuth 2.0: Use an account associated with a Microsoft Entra organization. Personal Microsoft accounts added to the organization's Entra tenant as members or guests can also be used.
• Microsoft Entra consent: If your organization restricts user consent to third-party applications, a Microsoft Entra administrator must approve the LinearB application before you can connect.
• PAT: You must be able to generate a PAT with the required read permissions in Azure DevOps. Organization Owner or Project Collection Administrator privileges are not required specifically for the Azure Boards integration.

---

Option A: Connect Using OAuth 2.0 (Recommended)

OAuth 2.0 provides secure authentication through Microsoft Entra without requiring you to create and manually renew a Personal Access Token.

1. In LinearB, go to Company Settings → Project Management.
2. Click Connect next to Azure Boards.
3. Select OAuth 2.0 as the authentication method. OAuth 2.0 is marked as Recommended.
4. Sign in with your Microsoft account associated with your organization's Microsoft Entra tenant.
5. Review the requested permissions and approve access.
6. Select the Azure DevOps organization you want to connect, if prompted.
7. Complete the authorization process.

After authorization succeeds, the Azure Boards integration appears as Connected.

LinearB begins processing Azure Boards data for project management tracking and analytics.

OAuth 2.0 Permissions

LinearB requests the following Azure DevOps permissions:

Permission	Scope	Purpose
User Profile	vso.profile	Read user profile information.
Project and Team	vso.project	Read project and team information.
Work Items	vso.work	Read work items, queries, boards, and area and iteration paths.

The authorization process also uses standard Microsoft identity scopes, including openid, profile, and offline_access, to authenticate the user and maintain the connection.

Read-only access: LinearB does not request write permissions for Azure Boards. The integration can access only the projects and work items visible to the authorizing user.

---

Option B: Connect Using a Personal Access Token (PAT)

Use a PAT if your organization prefers token-based authentication or uses Azure DevOps Server (self-hosted).

Step 1: Create a PAT in Azure DevOps

1. Sign in to Azure DevOps.
2. Click your profile picture in the upper-right corner and select Personal access tokens.
3. Click + New Token.
4. Enter a descriptive name, such as LinearB Azure Boards Integration.
5. Select the appropriate organization and set an expiration date according to your security policy.
6. Configure the following permissions with Read access:
   • User Profile (vso.profile)
   • Project and Team (vso.project)
   • Work Items (vso.work)
7. Click Create.
8. Copy the generated token and store it securely. You cannot view the token again after leaving the creation page.

Step 2: Connect Azure Boards to LinearB

1. In LinearB, go to Company Settings → Project Management.
2. Click Connect next to Azure Boards.
3. Select Personal Access Token (PAT) as the authentication method.
4. Enter the required Azure DevOps organization details.
5. Paste the PAT into the token field.
6. Click Connect.

After the connection is established, LinearB begins processing Azure Boards data.

---

Switch an Existing PAT Integration to OAuth 2.0

If Azure Boards is already connected using a PAT, you can switch to OAuth 2.0 without creating a new integration.

The migration preserves your existing project and board mappings, historical data, and integration configuration.

1. Go to Company Settings → Project Management.
2. Locate your existing Azure Boards integration and click Reauthorize. You can also begin the migration from the Switch to OAuth 2.0 banner, when displayed.
3. Select OAuth 2.0 as the new authentication method.
4. Sign in with your Microsoft account associated with the appropriate Microsoft Entra organization.
5. Select the same Azure DevOps organization used by your existing PAT integration.
6. Review the requested permissions and complete the authorization process.

LinearB validates the new OAuth connection before replacing the existing PAT authentication.

What Happens to Existing Data?

• Historical data: Existing Azure Boards data and historical analytics are preserved.
• Project and board mappings: Existing mappings remain associated with the integration.
• Failed authorization: If OAuth authorization fails or is cancelled, the existing PAT connection remains active.
• Successful authorization: LinearB switches the existing integration to OAuth 2.0 after validating the new connection.

---

Troubleshooting

Admin approval required

Your Microsoft Entra tenant may restrict users from granting consent to third-party applications.

Ask your Microsoft Entra administrator to approve the LinearB application, then try connecting again. Alternatively, use a PAT if permitted by your organization's security policy.

Unable to sign in with a personal Microsoft account

OAuth 2.0 requires an account associated with a Microsoft Entra organization.

Personal Microsoft accounts added to the organization's Entra tenant as members or guests may be used. However, a personal Microsoft account associated only with an MSA-backed Azure DevOps organization cannot use this OAuth flow.

If your account is not associated with a supported Entra organization, connect using a PAT instead.

No Azure DevOps organizations found

The authenticated account does not have access to an Azure DevOps organization.

Sign in with another account or ask your Azure DevOps administrator to grant access to the required organization.

Missing permissions to read projects or work items

The authenticated account does not have sufficient permissions to read the required projects or work items.

Ask your Azure DevOps administrator to grant the necessary access, or reconnect using an account with the appropriate permissions.

Reauthorization needed

An OAuth connection may require reauthorization if access is revoked, a Microsoft Entra Conditional Access policy changes, or the authorizing account is disabled.

Go to Company Settings → Project Management, locate the Azure Boards integration, and click Reauthorize.

PAT expired

Personal Access Tokens expire according to the expiration date configured in Azure DevOps.

Generate a new PAT with the required read permissions and reauthorize the integration.

For Azure DevOps Services (cloud), consider switching to OAuth 2.0 to avoid manual PAT renewal.

OAuth 2.0 option is not available

OAuth 2.0 is supported only for Azure DevOps Services (cloud).

Azure DevOps Server (self-hosted) integrations must use a PAT.

If you use Azure DevOps Services and OAuth 2.0 is not available, contact LinearB Support.

Different Azure DevOps organization selected

When switching an existing PAT integration to OAuth 2.0, LinearB checks whether the selected organization matches the current integration.

If the organizations differ, LinearB displays a warning and requires confirmation.

To preserve the existing organization's data association, select the same Azure DevOps organization used by the PAT connection.

---

Additional Notes

Supported Work Item Types

LinearB supports Azure Boards work item types except the following:

• Test Case
• Test Suite
• Test Plan

Linking Git Activity to Work Items

To help LinearB associate Git activity with Azure Boards work items, include the numeric Azure Boards work item ID in branch names, pull request titles, or commit messages.

Recommended branch naming format:

<work-item-ID>-<descriptive-title>

For example:

1234-add-user-authentication

This helps LinearB associate development activity with the relevant Azure Boards work item.

---

Next Steps

• Microsoft: Build Azure DevOps integrations with Microsoft Entra OAuth apps

Need help? Contact LinearB Support.