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
- Ensure the Users | Teams toggle is set to Teams under Settings → Users & Teams.
- Click + Add Team to add a team, fill in the fields → Save & Close.
- Important: You must first create a team you’d like nested within a group in order to create that group.
- 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.
- To nest a new team in an existing group, create the team with the desired Parent Group set, then Save & Close.
- 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
1. Define Team Git Scope
Where to configure Git Scope
- Select the team using the team dropdown (top-right).
- Click the gear icon → Team Settings → Git.
Steps — Assign repositories and/or services to a team
- In Team Settings → Git, review the list of available repositories and services.
- Select the repos and/or services this team owns or contributes to.
- Use the tabs Integrations & Repositories and Services to toggle between repo- and service-level scope.
- 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
- Go to Settings → Users & Teams and ensure the toggle is set to Users.
- Click + Add User.
- Fill in the user’s full name, email, and role.
- Define the user’s team scope and membership.
- 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
- Click the ⋮ menu next to the primary user.
- Select Merge Account.
- Choose the secondary (duplicate) account.
- 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
-
From Users view:
- Toggle to Users.
- Locate the user and click the ellipsis (⋮) → Edit Profile.
- Click + Add Team, select team(s) → Save & Close.
-
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:
- Locate the bot account under User & Teams → Users.
- Click the vertical ellipsis (⋮) on the far right of the user row.
- 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, orbasic), 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.
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
- Choose your IDP (Okta, Google, or Azure AD).
- Set up SAML SSO using your provider’s guide:
- (Optional) Enable SCIM in Okta if you want automatic provisioning:
- Test SSO with a small pilot group, then roll out broadly.
- (Optional) Enforce SSO so all users must authenticate via your IdP.