Skip to main content
Deutsch (Deutschland) Español Français Hebrew (Israel) Italiano Português

LinearB Enterprise Setup Guide

Heather Hazell
Updated

A complete implementation guide to configure LinearB for your engineering organization.

Overview

This guide walks you through setting up LinearB across your engineering organization using the recommended implementation flow:

  • Connect Git & PM systems
  • Clean data (branches, files, bots, metrics calc)
  • Organize groups, teams, and users
  • Map repos and PM boards to teams
  • Track releases, DORA, and incidents
  • Automate workflows with WorkerB & GitStream

Before You Begin

LinearB Enterprise Setup Checklist (Available in Google Sheets or Excel Format)

Use this checklist to track progress as you move through the Enterprise Setup Guide. We recommend sharing it with collaborators so everyone stays aligned on status and next steps.

Prerequisites:

  • LinearB admin privileges
  • Admin access to Git provider (GitHub, GitLab, Bitbucket, or Azure DevOps)
  • Admin access to your project management tool (e.g., Jira, ADO, Shortcut)
  • Slack or MS Teams admin rights (for WorkerB setup)

Estimated Time: 30–60 minutes
Roles Required: Admin

Milestone 1 — Integrations & Data Foundations

1. Connect Git

Expand to Learn More About Connecting Your Git Provider

Why
Your Git integration is the foundation for all delivery metrics in LinearB — including PR size, review time, cycle time, deployment detection, WorkerB automations, and project health insights.

Estimated Time: 5–20 minutes (varies by Git provider & repo volume)

Prerequisites

  • LinearB User: Admin
  • Access to your Git provider account (or service account)

 

Steps

  1. In LinearB, go to Settings → Integrations → Git.
  2. Click Add Integration.
  3. Choose your Git provider below and follow the native workflow.

    4. Connect GitHub

    GitHub (Cloud & Enterprise Server)

    Use this if your code is hosted on GitHub.com or GitHub Enterprise Server.

    Includes OAuth, PAT, and optional Organization-Level Webhook setup for real-time sync.

    Connect GitLab

    GitLab (Cloud & Self-Managed)

    Use this if your repos are on GitLab.com or a self-managed GitLab instance.

    Supports PAT authentication and optional webhook configuration.

    Connect BitBucket

    Bitbucket (Cloud & Server)

    Use this if you're hosted on Bitbucket Cloud or Bitbucket Server.

    Includes OAuth (Cloud) or PAT (Server) setup, plus server allowlisting details.

    Connect Azure Repos

    Azure DevOps Repos

    Use this if your repositories are in Azure DevOps (ADO) Repos.

    Requires an Azure DevOps PAT with read scopes for Projects, Teams, Code, Build, User Profile, and Graph.

  4. After connecting, wait for repositories to load (loading time is dependamt on volume).
  5. Select the checkboxes for repos you want LinearB to follow.
    Uncheck any repos you want LinearB to ignore.

Need help?
Please Contact support if you need assistance connecting multiple Git providers or migrating from one provider to another.

Sync Timing

  • First Load: ~2–3 hours, backfill period: 3 months
  • Maintenance Sync: every 2 hours, backfill period: 1 week
  • Maintenance Sync (with webhook): every 2 minutes, backfill: near real-time

Troubleshooting

  • Missing repos under “Add Repositories” → Insufficient OAuth/PAT permissions.
  • Repo data stale → Token permissions issue.
  • Connecting multiple Git providers → Please contact support
Video Walkthrough: Integrating Git Repositories in LinearB

2. Enable AI Services (Required for AI Insights and Iteration Summary)

Why enable this?
This toggle activates LinearB's AI capabilities across your organization, including:

  • AI Iteration Summary (automatic iteration-level analysis)
  • gitStream AI services (AI code review, AI PR context, AI insights)
  • Improved PR intelligence and automation behavior

Where to enable:
Go to Company Settings → General and toggle on:
“Enable LinearB AI Services”.

Notes:

  • This setting applies org-wide and must be enabled before AI-powered features can run.
  • To learn more about AI Iteration Summary, see: Feature – Iterations.

Disabling AI

Effects of disabling or not enabling AI Services

If you turn off AI Services, the following behavior applies across LinearB:

  • AI Automations (AI Review, AI Description) stop running.
  • GitHub Copilot and Cursor metrics dashboards continue reporting activity, since they use external APIs rather than LinearB AI Services.
  • Dependabot automations will not run.
  • Other dashboards (DORA, Delivery, Quality, Throughput) continue to function, but without AI-driven enhancements (eg., AI Iteration Summary).

 

3. Connecting Your Project Management Tool (Jira / Azure Boards / Shortcut)

Why
PM integration enables issue tracking, delivery metrics, planning accuracy, and investment profiles.

Supported tools

  • Jira Cloud
  • Jira Server (Self-Hosted)
  • Azure Boards
  • Shortcut

Prerequisites (by tool)

  • LinearB: Company Admin
  • Jira Cloud: Jira Admin with required OAuth scopes
  • Jira Server: Jira Admin with access to Application Links
  • Azure Boards: Org Owner or Project Collection Admin
  • Shortcut: Admin

 

Steps (High-Level)

  1. In LinearB, navigate to Company Settings → Project Management.
  2. Click Connect next to your project management tool and follow the on-screen authentication steps to grant LinearB access.
Video Walk through: Configuring Project Management In LinearB

 

Ready to Integrate? What PM tool are you using?

Jira Integration

Jira Setup (Cloud & Server)

Required Jira Cloud OAuth scopes
When configuring the Jira Cloud app, ensure the following scopes are granted:

  • read:jira-user
  • read:jira-work
  • read:project:jira
  • read:board-scope:jira-software
  • read:issue-details:jira
  • read:me
  • read:account
  • offline_access
  • read:sprint:jira-software
  • read:board-scope.admin:jira-software
  • read:jql:jira

Jira Cloud (OAuth)

Steps to Integrate Jira Cloud

What you’ll need: Jira Admin access

Recommended setup: Use a dedicated service account with Jira admin permissions to connect LinearB. This helps prevent future connection issues if the person who sets up the integration later leaves the company or has their access changed.
1. Start the Jira connection from LinearB
  1. In LinearB, go to Company Settings → Project Management.
  2. Click Connect next to Jira.
  3. Enter your Jira Cloud URL (for example, https://company.atlassian.net) and test the connection.
  4. Confirm the URL validation succeeds.
2. Create an OAuth application in Jira
  1. After your Jira URL is validated, click Connect to initiate the OAuth setup.
  2. LinearB will open Jira in a new browser tab (disable pop-up blockers if necessary).
  3. In Jira, click Create new link to establish the LinearB application.
  4. Select Generic Application as the Application Type.
  5. Check the Create incoming link option before proceeding.
  6. Click Continue to configure the application URL.
    You can safely ignore any message such as “no response was received from the URL” and continue.
  7. Copy and paste the required values between LinearB and Jira:
    • Copy the credentials shown in Step 2 in LinearB and paste them into the corresponding fields in Jira.
    • After continuing, copy the credentials from Step 3 in LinearB into the Jira authentication fields.
  8. Click Continue in Jira, then click Allow access in LinearB.

Once completed, LinearB will begin syncing Jira data. The initial backfill can take up to 2 hours.

Troubleshooting (Cloud)

  • Disable browser pop-up blockers if the OAuth window does not appear.
  • Ensure your Jira admin account is the one approving the integration.

Connect Jira Server to LinearB

Steps to Integrate Jira Server with LinearB:

What you’ll need: Jira Admin access

  1. In LinearB, go to Company Settings → Project Management.
  2. Enter your Jira base URL.
  3. Create an Application Link in Jira pointing to:
    https://app.linearb.io
  4. When prompted:
    • Application Type: Generic Application
    • Application Name: any descriptive label
  5. Ignore any “no response received” warnings and continue.
  6. Copy the Consumer Key / Public Key from LinearB into the Jira Application Link form.
  7. Authorize the app and return to LinearB.

  8. Select which Jira projects and boards LinearB should sync.

     

Optional: Configure rate limiting (if enabled on your server)

If rate limiting is enabled on your Jira Server, LinearB recommends the following minimum settings:

  • Requests per user: 120 requests per minute
  • Maximum concurrent requests: 120

These settings help prevent throttling and ensure uninterrupted data synchronization.

 

Troubleshooting (Server)

  • Connection fails: confirm the Application Link URL is exactly https://app.linearb.io.
  • Firewall issues: allow outbound traffic to 18.118.232.229.
  • Authentication fails: ensure you pasted the Consumer Key and Public Key correctly.

Azure Boards Integration

Recommended setup: Use a dedicated service account with Jira admin permissions to connect LinearB. This helps prevent future connection issues if the person who sets up the integration later leaves the company or has their access changed.
Azure Boards Setup
  1. In Azure, create a Personal Access Token (PAT) with:
    • Work Items (Read)
    • Analytics (Read)
    • Projects & Teams (Read)
  2. In LinearB, navigate to Company Settings → Project Management.
  3. Click Connect next to Azure Boards and follow the prompts.
  4. Paste the token into LinearB and click Connect.
  5. Select projects to follow (checkbox list of projects).

 

Shortcut Integration

Shortcut Setup
  1. In Shortcut, create a new API token.
  2. In LinearB, navigate to Company Settings → Project Management.
  3. Click Connect next to Shortcut and follow the prompts.
  4. Select workflows to sync.

PMT Integration Sync Timing

  • First Load: ~2–3 hours, backfill period: 3 months
  • Maintenance Sync: every 1 hour, backfill period: 1 week

 

Milestone 2 — Clean Data

Configure Release Detection

1. Configure Release Detection (4 Supported Methods)
Why
Releases define Deployment Frequency, Lead Time, and accurate cycle-time closure.

LinearB supports four release triggers:

Method A — Release by Tag (default)

  • Most popular option if you tag your releases.
  • Triggered when a Git push occurs to a tagged commit.
  • Every commit appearing in the tagged branch is considered released.
  • Supports regular expression (regex) to filter tag names by prefix/suffix.

Method B — Release by PR to a Dedicated Branch

Note: This method will cause Deploy Time to register as 0 (deploy time measured from PR approval to deploy is effectively skipped).

  • LinearB listens for PRs merged into dedicated branch(es) to define a release.
  • Any PR merged to a release branch (e.g. main) is treated as a deploy.
  • Set which branch(es) LinearB should listen to using a regex expression.
  • Default expression: ^(main|master|production|prod)$

Method C — Release by Direct Merge to a Branch

  • Used when your org merges directly into a dedicated release branch without using PRs.
  • LinearB detects the merged commit and marks included branches as deployed at time of merge.
  • Set which branch(es) to listen to by regex.
  • Default expression: ^(main|master|production|prod)$

Method D — Release by Deployment API

  • Report deployments and release events from your CI/CD system.
  • Best for teams relying on CI/CD for release management and seeking deployment metric accuracy.
  • Supports multi-stage release detection with LinearB’s custom stages.
  • Deployments are matched to merged branches using Git ancestry (i.e. is this branch’s commit an ancestor of the deployed commit?).

Note: Please follow this link to learn more details about our Deployment API

Where to Configure Release Detection

Org-wide Release Detection

Set the organization-wide release detection method
  1. In LinearB, go to Company Settings → Advanced.
  2. In the Release Detection section, select your desired release detection method.
  3. Click Save to apply your changes.
Override release detection per repo
Why
Individual repos can use a different release detection method than the organization default. For example, the org may use tag-based releases, while a specific team uses the Deployment API.
  1. In LinearB, Go to Company Settings → Git.
  2. Click the gear icon to the right of the repo you'd like to set specific release detection rules for.
  3. In the Release Detection section, select the desired release detection method for this team.
  4. Click Save to apply your changes.

 

Branch Exclusions

2. Set Branch Exclusions
Why
Exclude test or non-production branches that shouldn’t count toward metrics to improve data accuracy.

Defaults

^develop$
^development$
^master$
^staging$
^integration$
^release$
^production$
^main$

Custom Examples

test/*
demo/*
sandbox/*

Where to configure

Org-Wide Branch Exclusion

Set the organization-wide branch exclusion configuration
  1. In LinearB, go to Company Settings → Advanced.
  2. Scroll to the Exclude Branches section.
  3. Add one regular expression per line to describe the branch patterns you want LinearB to ignore.

Branch Exlusion per Repo

Override branch exclusion configuration per repo
Why
Individual teams can use a different branch exclusion configuration than the organization default.
  1. Go to Settings → Git.
  2. Select the gear icon to the right of the repo you'd like to configure differently.
  3. In the Exclude Branches section, add one regular expression per line to describe the branch patterns to ignore for this repo.

 

File Exclusions

3. Set File Exclusions
Why
Prevents non-code files from affecting PR size, new code %, and overall accuracy.

Defaults

.*package-lock\.json$
.*dist/.*\.js
.*public/assets/.*\.js
.*\.(ini|csv|xlsx|txt|doc|rtf|ipynb|resx)$

Where to configure

Set the organization-wide file exclusion configuration
  1. In LinearB, go to Company Settings → Advanced.
  2. In the Exclude File Extensions section, add one regular expression per line to describe the file patterns LinearB should ignore.
Override file exclusion configuration per repo
Why
Individual teams can use a different file exclusion configuration than the organization default.
  1. Go to Settings → Git.
  2. Select the gear icon to the right of the repo you'd like to configure differently.
  3. In the Exclude File Extensions section, add one regular expression per line to describe the file patterns to ignore for this repo.

 

Draft Pull Requests

4. Configure Draft Pull Requests
Why
Draft Pull Requests ensure that early or incomplete work does not distort Cycle Time, Pickup Time, or Review Time. LinearB automatically excludes draft PRs from key metrics until they are ready for review, giving you a cleaner and more accurate view of delivery performance.

How LinearB identifies draft PRs

LinearB can treat a pull request as draft when it matches either (or both) of the following:

  • Has one of your configured labels for draft work.
  • Has a title that matches a regular expression pattern you define.

Where to configure Draft Pull Requests

Set the organization-wide draft pull request configuration
  1. In LinearB, go to Company Settings → Advanced.
  2. Scroll to the Draft Pull Requests section.
Override draft pull request configuration per repo
Why
Individual teams can use a different draft PR configuration than the organization default.
  1. Go to Settings → Git.
  2. Select the gear icon to the right of the repo you'd like to configure differently.
  3. Open the Draft Pull Requests section.

Steps — Configure labels and title pattern

  1. In the Draft Pull Requests section, add the labels your organization uses for draft work. For example:

    • wip
    • do_not_merge
    • work in progress
    • work_in_progress

    Any PR with one of these labels will be treated as a draft.

  2. Optionally, specify a regular expression for PR titles that should be treated as draft. A common example is:
    ^.*wip.*$
  3. Click Save to apply your changes.

Note: Changes to draft PR settings are applied from the time of the saved configuration, moving forward.

Best practices

  • Standardize on one or two labels (for example, wip and do_not_merge) across all teams.
  • Use labels for clarity, and the title pattern as a safety net for ad-hoc “WIP” titles.
  • Review your existing PR conventions before changing these settings, so historical behavior remains intuitive for developers.

 

Exclude Bots

5. Excluding Bot Accounts
Why
Bot commits can inflate activity and PR metrics if not excluded.

How:

  1. Locate the bot account under User & Teams → Users.
  2. Click the vertical ellipsis (⋮) on the far right of the user row.
  3. Delete User 

Screenshot 2026-02-06 at 3.26.19 PM.png

st-item-id="edfd291479dd5ed18b002b4af0d5aa7a9"Bot exclusion will soon be configurable in-product.

 

Global Metric Calculations

6. Configure Global Metric Calculations
Why
Determines how PR Size, Cycle Time, Pickup Time, Review Time, and Deploy Time aggregate.

Options & Examples

  • Average – Sum ÷ count
    Example: 4 PRs took 2, 4, 6, and 8 hours → (2 + 4 + 6 + 8) ÷ 4 = 5 hours average.
  • Median – Middle value
    Example: PR merge times are 2, 4, 6, 8, 10 → Median = 6 hours.
  • 75th Percentile – 75% of PRs are faster than or equal to this.
    Example: Most PRs take 2–6 hours but a few take 10+ → 75th percentile ≈ 6 hours (captures the “typical upper range”).
  • 90th Percentile – 90% of PRs are faster than or equal to this.
    Example: Most PRs take 2–8 hours, but a few outliers take 20+ → 90th percentile ≈ 8 hours (shows performance excluding rare outliers).
How to choose the right calculation method

Different engineering teams prefer different aggregation strategies depending on their size, workflow variability, and how sensitive they are to outliers. Below is guidance to help you choose the method that best reflects your team’s “true” performance.

  • Average (Mean)
    Best when your team’s PR sizes and cycle times are relatively consistent. 
    Why choose it: You want a simple, familiar metric and your data does not contain extreme outliers.
  • Median
    A stable representation of your “typical” PR because it ignores outliers on both ends. 
    Why choose it: Your workflow produces occasional very large or unusual PRs, and you don’t want those to skew the overall metric.
  • 75th Percentile (Industry Standard)
    Captures the performance of most PRs while still reflecting friction in the system. 
    Why choose it: You want a balanced view that smooths outliers but still highlights when work takes longer than expected. Most DORA-focused teams prefer this.
  • 90th Percentile
    Highlights the slowest part of your process without being dominated by true one-off outliers. 
    Why choose it: You want more sensitivity to delays — great for teams optimizing flow efficiency or monitoring tail behavior.

Where to configure
Configure at Company Settings → General → Metrics Calculation.

 

Video Walkthrough: Advanced Company Settings in LinearB
 

Milestone 3 — Your Org Structure

1. Create & Manage Teams in LinearB

Create Groups & Teams
Why
Clean team structure ensures accurate KPI reporting, PR ownership, and dashboards.

Group Hierarchy Notes

  • Groups can nest.
  • Used for director-level or org-level reporting.
  • Teams belong inside groups.
  • Users must belong to teams for accurate metrics.

Team & Group Setup Steps

  1. Ensure the Users | Teams toggle is set to Teams under Settings → Users & Teams.
  2. Click + Add Team to add a team, fill in the fields → Save & Close.
  3. Important: You must first create a team you’d like nested within a group in order to create that group.
  4. Once at least one team exists, click + Add Group, fill in the fields, and under Subgroups & Teams, select the team(s) you’d like nested within it.
  5. To nest a new team in an existing group, create the team with the desired Parent Group set, then Save & Close.
  6. To revise a team’s group, click the pencil icon next to the team and edit the Parent Group field.

 

1a. (Optional) Manage teams via API

By default, teams are created and managed in the LinearB UI (for example from Settings → Users & Teams). If your organization prefers to manage teams programmatically, you can also use the Teams Management API v2.

(Optional/Advanced) Use LinearB's Teams API to manage teams 
Why
The Teams V2 API provides full control over managing teams and their structure within LinearB, including bulk operations.

With the Teams API you can:

  • Search existing teams.
  • Create new teams (including parent / child hierarchy, initials, and color).
  • Update team properties.
  • Delete teams that are no longer needed.
  • Manage team membership:
    • Get current members
    • Set (replace) all members in bulk
    • Add members
    • Remove specific members

NOTE:This option is useful if you want to keep LinearB teams aligned with an external source of truth by calling the API from your own automations or integration services. For endpoint details and request examples, see the Teams V2 API documentation .

 

1b. Configuring Team Settings

Please watch the 2 minute video below to learn about about Team Configuring Team Settings within your LinearB instance.

 

Create & Manage Users in LinearB

2. User Management

NOTE: The following Instructions are for our new User Management UI (Users & Teams). If you are a customer pre-December 2025, please reference our guide for instructions on migrating to the new User Management UI. 

Why
Centralized user management (under Settings → Users & Teams) allows you to:

  • Add, remove, and modify users.
  • Manage role-based permissions (Viewer, Editor, Admin).
  • Manage Git and PM connections.
  • Manage team membership and licensing.

Adding a New User

  1. Go to Settings → Users & Teams and ensure the toggle is set to Users.
  2. Click + Add User.
  3. Fill in the user’s full name, email, and role.
  4. Define the user’s team scope and membership.
  5. Click Save & Close.

When creating or modifying user permissions, ensure all active users have correct access. See permissions matrix below as reference.

User Role Permissions Matrix

Access Admin Editor Viewer Basic
Company Settings View/Edit No Access No Access No Access
Connect Git/PM/Slack/MS Teams View/Edit No Access No Access No Access
User Settings View/Edit/Invite No Access No Access No Access
Teams Settings & Team Contributors View/Write View/Write* No Access No Access
Dashboards View/Write View/Write* View* No Access
Projects Tab View View* View* No Access
Teams Tab View/Write View/Write* View/Write* No Access
Surveys View/Create/Delete Response Response Response
Metrics Tab / Reports Public & Private Reports
View/Create/Delete		 Private Reports
View/Create/Delete		 View No Access
Project Delivery Trackers View/Create/Edit/Delete View/Create/Edit/Delete View No Access
Resource Allocation View/Edit View No Access No Access
Investment Strategy Report View/Edit View View No Access

* Editors cannot create new teams; they can only edit existing teams.

* Access for assigned teams only

Merging Users

Why
When you have multiple Git organizations or connections, developers may appear under multiple emails/usernames. LinearB supports cross-platform merges so all data for a user is unified.

Steps

  1. Click the ⋮ menu next to the primary user.
  2. Select Merge Account.
  3. Choose the secondary (duplicate) account.
  4. Confirm to merge.

Adding an Existing User to a Team

Why
Users on a team are the contributors LinearB will follow and count toward that team’s metrics.

Note: Users who are on a team are the users who count toward your billable license count.

Two options

  1. From Users view:
    • Toggle to Users.
    • Locate the user and click the ellipsis (⋮) → Edit Profile.
    • Click + Add Team, select team(s) → Save & Close.
  2. From Teams view:
    • Toggle to Teams.
    • Hover over the team row and click the pencil icon.
    • Search for and select the user in the Direct Users field → Save & Close.

Frequently Asked Question:
“If a user is not assigned to a team, do they count toward my license?”

Answer: No. Only users who are added to at least one team count toward your billable license count. Users who exist in the system but are not on a team do not count toward licensing and do not appear in team metrics. strong>Frequently Asked Question:
“If a user who was not previously assigned to a team joins a team, does any of their git history get brought in?”

Answer: Yes. We will bring in 3 months of git history. If you do not want historical data brought in, you check the box at the bottom of the Edit Team page that states, This member just joined the team. (Do not include previous work as part of the team's work) before saving.

Optional: Manage users via the LinearB Users API

In addition to managing users from the LinearB UI or via your identity provider, you can use the Users API to automate user lifecycle tasks from your own systems and scripts. The Users API provides full CRUD operations on LinearB users, including roles, team scopes, and identity metadata.

  • Search users by name, email, role, or ID and page through results.
  • Create users with the correct role (admin, editor, viewer, or basic), team scopes, and optional coaching access.
  • Update users to adjust names, emails, roles, or team membership when responsibilities change.
  • Delete users by ID when they no longer need access to LinearB.
  • Attach extra emails / IDs to help you map LinearB users to your internal systems.
Good for: organizations that want to drive onboarding/offboarding from an internal system of record (e.g., an internal admin tool or HRIS sync) using API calls instead of manual UI updates.

For full request/response details and examples, see the API reference:
Users API (New) .

 

SSO & SCIM

3. Authentication, SSO & SCIM (Optional)
Why configure this during onboarding?
Setting up SSO (and SCIM) early ensures users log in securely with corporate credentials and reduces manual user management as you roll LinearB out across teams.

What you can configure

  • SAML SSO with:
    • Okta
    • Google Workspace (GSuite)
    • Azure AD / Microsoft Entra
  • SCIM Provisioning (Okta only)

Where to configure in LinearB:
Settings → SSO

If you do not see the SSO tab or the SCIM tab (Okta only), please contact support to enable these features.

Important: SSO user provisioning behavior:
  • When Single Sign-On (SSO) is enabled, users are provisioned in LinearB only after their first successful SSO login.
  • LinearB automatically attempts to unify user identities across SSO, Git providers, and project management tools.
  • This automatic unification requires a 100% email address match between the SSO-provisioned user and the Git identity.
  • If email addresses do not match exactly, the user may appear as multiple accounts (for example, one SSO user and one Git user) and a manual merge is required to ensure all activity, permissions, and historical data are associated with the correct user.

Note: Correct identity merging is especially important for features such as Surveys, where responses must be attributed to the correct user account.


SSO Gotchas:

  • Until a user logs in for the first time, they may not appear in Settings → Users & Teams. To avoid confusion, ask new users to log in once via SSO before assigning roles or teams.
  • You cannot modify permissions (for example, promote a user from Viewer to Admin) until the user has logged in at least once and a platform user record exists.
  • If an admin attempts to elevate permissions for a user who has not logged in yet, the action will fail because the user is not yet provisioned.

 

Recommenced onboarding flow

  1. Choose your IDP (Okta, Google, or Azure AD).
  2. Set up SAML SSO using your provider’s guide:
  3. (Optional) Enable SCIM in Okta if you want automatic provisioning:
  4. Test SSO with a small pilot group, then roll out broadly.
  5. (Optional) Enforce SSO so all users must authenticate via your IdP.

 

Milestone 4 — Map Work Sources to Teams

Git Team Scope

Define a team's git scope through repositories & services

Why
Git Scope determines which repositories and services LinearB uses when calculating a team’s metrics. This ensures each team’s dashboards reflect only the work they own — preventing noise, duplication, and misattribution.

When this is especially helpful

  • When contributors work across multiple teams.
  • When repos or services are shared or partially owned across teams.
  • When teams want clean, accurate Cycle Time, PR activity, and Deployment metrics.

By defining Git Scope, LinearB ensures:

  • Contributor work is attributed correctly to the right team.
  • No double-counting of branches, PRs, or deployments.
  • Dashboards only display activity for repos and services relevant to that team.

Example use case: Git Repo Filters are useful for teams that are responsible for services that are coded in specific repositories when you have team members that work across multiple services. It allows the team to narrow their metrics to their focus areas, rather worrying about the cycle time for work outside of their projects. You can also narrow the team metrics by services.

1. Define Team Git Scope

Where to configure Git Scope

  1. Select the team using the team dropdown (top-right).
  2. Click the gear icon → Team Settings → Git.

Steps — Assign repositories and/or services to a team

  1. In Team Settings → Git, review the list of available repositories and services.
  2. Select the repos and/or services this team owns or contributes to.
  3. Use the tabs Integrations & Repositories and Services to toggle between repo- and service-level scope.
  4. Click Save to apply Git Scope filtering.

What happens next:

  • A Git Scope banner appears on team dashboards, Goals, and Activity pages.
  • Metrics automatically filter to only the selected Git Scope.
  • Branches, PRs, and deployments outside the scope are hidden from this team’s views.

Managing Git Scope

  • Refine over time: update Git Scope anytime in Team Settings → Git.
  • Temporarily disable filtering: toggle off the Git Scope banner in dashboards.
  • Permissions: only Admins and Editors can modify Git Scope.

Tip: Teams with cross-team contributors benefit the most from Git Scope. When the same developer contributes to multiple teams, Git Scope ensures their work is attributed correctly and never counted twice.

Common Questions

Can I override Git Scope filtering?

Yes. You can toggle off the Git Scope filter in dashboards if you need to view all data.

What happens if a team contributor works outside the selected Git Scope?

Any branches, commits, or PR/MRs outside the defined Git Scope will not appear in the filtered team view.

Who can modify the Git Scope?

Only Linear Users with a Editor or Admins can adjust Git Scope in Team Settings.

Does Git Scope change how contributors are assigned to a team?

No. Git Scope only affects which repositories appear in team dashboards. Contributor assignment still depends on activity across repos connected to your organization.

Will Git Scope remove data or delete historical activity?

No. Git Scope is a filter, not a data deletion mechanism. All historical activity remains accessible when Git Scope is turned off.

Should every team use Git Scope filtering?

It’s recommended if teams share contributors or repositories. Git Scope helps prevent double-counting and keeps team metrics focused and accurate.

Can a repository belong to multiple teams?

Yes. Some organizations intentionally allow shared repos. In those cases, Git Scope ensures each team still sees only the activity they choose to include.

 

Associating Boards/Projects

Why
Mapping boards/projects to teams allows better task tracking, iteration-based decision making, estimated completion times, and better visibility into context switching.

2. Associate Relevant Boards (Jira) or Projects (Azure) to Teams

Steps

  1. Select the team in the dropdown at the top-right of the window.
  2. Click the gear icon → Team Settings → Project Management.
  3. Select the relevant board(s)/project(s) from the dropdown list.
  4. Select the methodology: Scrum or Kanban as appropriate.
  5. Save to confirm the assignment.

Note: Depending on the amount of data, allow up to 1 hour for LinearB to filter the data accordingly.

Troubleshooting

  • Board/Project not appearing in dropdown → Ensure the board and related project are checked to follow in Company Settings → Project Management (see Milestone 1, Step 2).

 

Milestone 5 — DORA & Incident Tracking

1. Configure DORA Metrics 
Why
Enables full visibility into Lead Time (Cycle Time), Deployment Frequency, MTTR, and CFR.

 

How LinearB calculates Cycle Time phases

  • Coding Time – from the first commit on a branch to PR/MR creation.
  • Pickup Time – from PR/MR creation to when review begins.
  • Review Time – from review start to PR/MR merge.
  • Deploy Time – from merge to production release (based on your Release Detection settings).

To get complete DORA coverage in LinearB, make sure you have:

  • Release Detection configured (see Milestone 2 – Clean Data).
  • Incident Tracking configured (see Step 12, Configure Incident Tracking).

  • A confirmed Coding Time strategy (below).

     

Configure your Coding Time strategy

Goal: Ensure “work started” in LinearB aligns with how your teams actually begin coding.

Default Coding Time in LinearB:

  • Start: first commit on a branch
  • End: when PR/MR is opened

Optional alternative strategy (when using a PM tool):

  • Start: when an issue linked to a branch is moved to In Progress
  • End: when PR/MR is opened

Use the alternative strategy if you want Coding Time to reflect the moment work officially begins in your PM workflow, not just the first commit.

Where to configure Coding Time strategy

  1. In LinearB, go to Company Settings → Advanced.
  2. Locate the Coding Time Strategy section and choose your preferred option.
  3. Click Save to apply.

 

2. Configure Incident Tracking 
Why
Enables LinearB to detect production failures, associate them with deployments, and calculate Change Failure Rate (CFR) and Mean Time to Recovery (MTTR). This is critical to understanding reliability, stability, and the end-to-end impact of engineering work.

 

Where to Configure Incidents

Set the organization-wide incident detection method

  1. In LinearB, go to Company Settings → Project Management → Incidents.

Once API Integration is selected at the organization level, incidents reported via the API are used to calculate CFR and MTTR for your LinearB environment.

Override incident detection per team

Individual teams can use a different incident detection method than the organization default. For example, the org may use project-management–based incidents, while a specific team uses the Incident API.

  1. In LinearB, select the team in thr drop down (top right corner) that should use a different incident detection method.
  2. Go to Team Settings, open the Project Management tab, then click the Incidents tab.

This affects how LinearB calculates CFR and MTTR for that team and any parent groups that aggregate it.

From here you can choose:

  • Rules-based detection (detect incidents using fields in your PM tool)
  • API-based detection (detect incidents through direct API calls from your incident system)

Option 1 — Rules-Based Incident Detection (Most Common)

This method uses data from your PM tool (Jira, Azure Boards, etc.) to recognize when an issue becomes an “incident.”

Where to Configure

Company Settings → Project Management → Incidents → CFR 
Company Settings → Project Management → Incidents → MTTR

CFR Rule Builder

Define how LinearB should recognize a “critical bug” that counts toward CFR.

You can define incidents using:

  • Issue type (e.g., Bug, Incident, Sev-1)
  • Labels (e.g., production, hotfix, outage)
  • Status (e.g., In Progress → Resolved)
  • Custom fields (severity, environment, impact level)
  • Date fields
    • Start time — when the incident began
    • End time — when the incident was resolved

CFR Calculation: CFR = Incidents / Deployments

MTTR Rule Builder

Defines how LinearB should recognize the start and end of an incident to calculate MTTR.

You can define MTTR timing using:

  • A status transition (e.g., “In Progress” → “Resolved”)
  • A date field (e.g., started_at, ended_at)
  • Custom incident timing fields

MTTR Calculation: MTTR = Time from incident start → incident resolution

Option 2 — API-Based Incident Detection

When to use: Your incident system is external (PagerDuty, Opsgenie, ServiceNow, in-house alerting), or you want precise incident timing beyond what exists in your PM tool.

Where to Configure

Company Settings → Project Management → Incidents → API Integration.

Steps

  1. Go to Settings → API Tokens and create a token for your incident system.
  2. Switch the incident detection method to API Integration.
  3. Send incident lifecycle events to the LinearB Incident API:
    • create (incident opened)
    • update (optional fields during handling)
    • resolve (incident ended)
  4. Each event must include:
    • provider_id (unique identifier from your system)
    • title
    • http_url (link to the incident)
    • issued_at (when the incident occurred)
    • started_at and ended_at for MTTR

Note: Please follow this link to learn more details about our Incident API

How LinearB Matches Incidents → Deployments

Regardless of detection method (Rules or API), LinearB automatically links incidents to deployments using Git ancestry analysis:

  • LinearB evaluates the commit SHA or ref of each deployment.
  • Checks if the PR’s tip commit is an ancestor of that deployed ref.
  • If true, the PR is marked as deployed.
  • If a deployed PR is associated with an incident, CFR increments and MTTR is calculated.

Milestone 6 — AI & Automation: WorkerB + gitStream

1. Confirm LinearB AI Services is Enabled (Required for AI features)

Note: This is the same org-wide AI toggle mentioned in earlier milestones. If you’ve already enabled LinearB AI Services, you can simply confirm it’s still turned ON and move on.

Why
LinearB AI Services power AI-enhanced features across the platform, including:

  • gitStream AI automations (AI code review, PR descriptions, auto-analysis)
  • AI Iteration Summary (automated iteration insights for managers)
  • AI-powered delivery insights throughout dashboards and reports

Without enabling AI Services, gitStream’s AI actions and AI Iteration Summary will not run, even if gitStream is installed correctly.

Where to enable AI Services

  1. Go to Company Settings → General.
  2. Scroll to the AI Services section.
  3. Toggle Enable LinearB AI Services to ON.

Recommended: Enable this before rolling out gitStream or WorkerB to ensure AI insights collect from day one.

Effects of disabling, or not enabilng, AI Services

If you turn off AI Services, the following behavior applies across LinearB:

  • AI Automations (AI Review, AI Description) stop running.
  • GitHub Copilot and Cursor metrics dashboards continue reporting activity, since they use external APIs rather than LinearB AI Services.
  • Dependabot automations will not run.
  • Other dashboards (DORA, Delivery, Quality, Throughput) continue to function, but without AI-driven enhancements (eg., AI Iteration Summary).

 

AI Tooling

2. AI Tools Configuration 
Why
Essentials provides visibility into AI-assisted development, so you can measure usage, adoption, and the downstream impact of AI-generated code.

Supported AI tools

  • GitHub Copilot
  • Cursor

Where to configure

Go to Company Settings → AI Tools to enter API tokens for Copilot and/or Cursor. Once configured, LinearB automatically detects AI contributions and attributes them to developers.

Ensure the required scopes are checked: read:org, read:user, manage_billing:copilot

Outcome: AI activity is tracked per developer, included in PR analysis, and available to gitStream rules.

 

WorkerB

3. Enable WorkerB (Slack or MS Teams)

Why
Automates cycle-time improvements with nudges, reminders, and alerts.

Included:

  • 13a. Configure Team Notifications
  • 13b. Enable WorkerB Personal Notifications

What communication app do you use?

Slack

Slack – Prerequisites

  • LinearB User: Admin
  • Slack: Admin
  • Your Slack workspace should include the public teams/channels you want to connect.
  • To connect a private channel, please contact support with the Slack channel name, Slack channel ID, and LinearB team name.

Slack – Steps

  1. In LinearB, navigate to Settings → Company Settings → Slack.
  2. On the redirect to Slack authorization, click Allow (only required for initial workspace connection).
  3. Verification: you should receive a confirmation message in your Slack workspace.

Connect Additional Teams (Slack)

  1. If you haven’t already, add a team in LinearB (see Milestone 3, Step 7).
  2. In Settings → Company Settings → Slack, connect the LinearB team by clicking Connect Slack and ensure Status is toggled ON for that team.
MS Teams

MS Teams – Prerequisites

  • LinearB User: Admin
  • MS Teams: Admin
  • WorkerB installed in MS Teams.

MS Teams – Steps

  1. In LinearB, navigate to Settings → Company Settings → MS Teams.
  2. Note: If you do not see this tab available,contact support to enable it.
  3. Follow prompts to connect your Teams tenant and channels.

Connect Additional Teams (MS Teams)

  1. If you haven’t already, add a team in LinearB (see Milestone 3, Step 7).
  2. In Settings → Company Settings → MS Teams, connect the LinearB team by clicking Connect and ensure Status is toggled ON for that team.

Note: If your organization uses an on-prem Git provider, WorkerB setup must be completed manually. Please contact support for assistance.

Configure Team Notifications for Visibility

Why
Keep teams aligned in Slack/Teams with WorkerB notifications. Surface potential issues early (stale PRs, long pickup time), highlight progress (deploys, merged PRs), and alert when goals are approaching or exceeded.

Prerequisites

  • WorkerB is installed in your Slack or MS Teams workspace and connected to LinearB.
  • LinearB User: Admin or Team Editor.

Steps

  1. Navigate to Settings → Team Settings → Goals.
  2. Click Edit to customize each goal’s threshold.
  3. Select how you’d like to be notified:
    • Send your team a heads up when goals are at risk.
    • Send a notification when a PR outside of the goal threshold has been merged.
    • Optionally, track team progress on the Goals dashboard.

Troubleshooting: For further assistance, please contact support.

Enable WorkerB Personal Notifications for Developers

Why
Developers receive real-time WorkerB notifications for their pull requests, helping them stay on top of reviews, approvals, CI status, and more.

Prerequisites

  • WorkerB is installed in your Slack or MS Teams workspace and connected to LinearB.

MS Teams & Slack Personal Notification Setup

MS Teams – Personal Setup
  1. Open the WorkerB bot in Teams.
  2. Type LinkUser in the chat.
  3. In the popup window, click Link my account → you’ll be redirected to the LinearB browser login.
  4. Login using your Git provider credentials to authenticate and link your Git identity.

Tip: Pin WorkerB in Teams by clicking the three dots next to the chat and selecting Pin.

Alert Customization (Teams)

  1. Open WorkerB chat in Teams.
  2. Type Pref to open preferences.
  3. Edit selections as desired and save.

Available Commands in Teams DM

  • LinkUser – Link your Teams account with your LinearB account.
  • Invite – Invite your team members to use personal notifications and commands.
  • Pref – Customize your personal notification preferences.
  • Prs – Display all open PRs you’ve authored.
  • Prs long – Display long-living PRs.
  • Prs done – Display completed PRs.
  • Updates – Display your latest PR updates.
  • Reviews – Display all your open PR reviews.
  • Unlink – Unlink your Teams account from LinearB.
Slack – Personal Setup
  1. Type /lb connect in any DM.
  2. If you’re not already connected, you’ll receive a prompt to connect with your Git server.
  3. Click Let’s do it! to open the LinearB browser login.
  4. Login using your Git provider credentials to authenticate and link your Git identity.

Alert Customization (Slack)

  1. In Slack, type /lb pref to open your Personal Preference Panel.
  2. Edit selections as desired and save.

Available Commands in Slack DM

  • /lb connect – Connect your Slack handle to LinearB.
  • /lb help – Display available WorkerB commands.
  • /lb updates – View updates on your open PRs.
  • /lb reviews – Show PRs assigned to you for review.
  • /lb prs – List all open PRs you’ve authored.
  • /lb prs long – List long-living PRs.
  • /lb prs done – List your recently completed PRs.
  • /lb pref – Customize alert preferences.
  • /lb unlink – Unlink your Slack and Git accounts.
  • /lb invite – Invite teammates to connect WorkerB.

gitStream

4. Enable gitStream Automation

gitStream automates PR workflows, reduces manual review burden, enforces standards, and supports AI-assisted review. Enabling it early accelerates time-to-value and powers key AI insights in LinearB.

Why enable gitStream + AI now?

As teams adopt AI coding tools, most leaders lack visibility into whether AI is actually improving delivery or introducing quality risks. LinearB helps you measure the real impact of AI-assisted development.

  • Compare delivery speed for AI-assisted vs. non-AI PRs.
  • See how much AI-generated code is merged — and how often it requires rework.
  • Identify which AI-assisted PRs introduce incidents or rollbacks.

Enabling gitStream + AI during onboarding ensures you begin collecting AI performance data from day one.

Install gitStream

Installation depends on your Git provider. Use the guide that matches your environment:

Not sure which guide applies? See the GitStream Enablement Hub.

Enable gitStream in LinearB

After installation is complete:

  1. Go to Automations → GitStream in LinearB.
  2. Select the repositories where you want gitStream to run.
  3. Enable the recommended base rules (best for most teams starting out).

  4. Optional: Add additional rules (Advanced)

    Once your team is comfortable, you can add custom YAML rules to support your specific workflow.

    rules:
  - name: safe_changes
    if: low_risk
    approve: auto

For help choosing the right rules for your teams, see the GitStream Quick Start.

Verify Implementation

You should now see:

  • Git syncing
  • PM syncing
  • Accurate branch/file exclusions
  • Correct team structure
  • Repos mapped to teams
  • Release detection functioning
  • DORA metrics populating
  • WorkerB notifications
  • GitStream automations firing as expected

🎉 Implementation Complete!
Your LinearB system is now fully configured for enterprise-scale visibility, performance measurement, and workflow automation.

Next Steps

Related articles