Get Started - LinearB Enterprise Setup Guide

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.
GitHub (Cloud & Enterprise Server)

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

• GitHub Cloud Integration Guide
• GitHub Enterprise Server (On-Prem) Guide

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

GitLab (Cloud & Self-Managed)

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

• GitLab Cloud + Self-Managed Integration Guide

Supports PAT authentication and optional webhook configuration.

Bitbucket (Cloud & Server)

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

• Bitbucket Cloud + Server Integration Guide

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

Azure DevOps Repos

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

• Azure Repos Integration Guide

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

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 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.

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

Prerequisites

• LinearB user: Admin
• Azure: Org Owner or Project Collection Admin
• Jira: 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.

What PM tool are you using?

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

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

Defaults

Custom Examples

Where to configure

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

Defaults

Where to configure

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

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.

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

Steps

• Please contact support to send bot email addresses for exclusion.
• Bot exclusion will soon be configurable in-product.

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).

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

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.

The following Instructions are for our new User Managment 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.

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

* Access for assigned teams onl

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.

Coming Soon: filters to quickly identify billable and non-billable users, and to filter by status (active, inactive, hidden).

Note: SSO and SCIM are not enabled by default. Please contact LinearB Support to enable these features for your organization.

Why configure this during onboarding?
Setting up SSO (and SCIM for Okta) 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

Recommended onboarding flow

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

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.

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.

Common Questions

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

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).

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).

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

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.

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.

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.

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?

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.

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.

Install gitStream

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

• GitStream for GitHub Cloud
• GitStream for GitHub Enterprise Server
• GitStream for GitLab (Cloud & Self-Managed)
• GitStream for Bitbucket Cloud
• Managed Mode (Essentials plan)

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).
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.