Creating & Managing Teams + Users in LinearB

Create & Manage Teams in LinearB

1. Create Groups & Teams

Why
Clean team structure ensures accurate KPI reporting, PR ownership, and dashboards. LinearB will only collect data for users who are assigned to a team(s).

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.

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

Use LinearB's Teams API to manage teams (advanced)

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

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 .

 

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

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

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.

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.

Create & Manage Users in LinearB

  Upon log in you will see your git and pm tool contributors already available to begin adding to teams. These users will not yet have access to the LinearB UI. To give a user UI access you will need to invite them using the + add user button on the top right.

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.

Excluding Bots and Removing Users

Bot exclusions
Why:
Prevents CI/CD bots or automation accounts from appearing as “active contributors” or inflating commit counts.

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 

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

(Optional) SSO & SCIM 

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.

---

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.

---