Modeling teams in Sourcegraph

This feature is in Experimental stage and might change in the future.

Teams in Sourcegraph are groups of users with a common handle. Teams are structured as a tree, so teams can have child teams.

Example team structure that can be modeled:

SHELL
Engineering
├─ Security
├─ Code Graph
│  ├─ Batch Changes
│  ├─ Code Insights
├─ source
│  ├─ Repo Management
│  ├─ IAM
Product

Teams in Sourcegraph are usable in code ownership, and other features in the future. Teams can be code owners and will influence the code ownership experience. You can search for code owned by a specific team, and in the future advanced ownership analytics will be informed by given team structures.

Configuring teams

Teams can either be defined directly in Sourcegraph, or be ingested from external systems into Sourcegraph using src-cli. A team name must be globally unique, and the global namespace for names is shared among users, teams, and orgs.

From the UI

Go to Teams from the user navbar item. On this page, click "Create team". A team needs to have a unique name and can optionally take a display name. Additionally, you can add a parent team to build a tree structure as outlined above.

After hitting create, you will be redirected to the team page where you can add Sourcegraph users as team members.

NOTE: It's common to define teams in Sourcegraph from a third party system. Teams defined from src-cli using the -read-only flag cannot be modified from the UI to prevent state drift from external systems.

From the CLI

If you prefer a command line based approach, or would like to integrate an external system of record for teams into Sourcegraph, src-cli provides commands to manage teams:

BASH
# List configured teams. Lists root teams, using -parent-team can read child teams.
src teams list [-query=<query>] [-parent-team=<name>]
 
# Create a new team.
src teams create -name=<name> [-display-name=<displayName>] [-parent-team=<name>] [-read-only]
 
# Update a team.
src teams update -name=<name> [-display-name=<displayName>] [-parent-team=<name>]
 
# Delete a team.
src teams delete -name=<name>
 
# List team members.
src teams members list -name=<name> [-query=<query>]
 
# Add a new team member. See user account matching for details on how this works.
src teams members add -team-name=<name> [-email=<email>] [-username=<username>] [-id=<ID>] [-external-account-service-id=<serviceID> -external-account-service-type=<serviceType> [-external-account-account-id=<accountID>] [-external-account-login=<login>]] [-skip-unmatched-members]
 
# Remove a team member. See user account matching for details on how this works.
src teams members remove -team-name=<name> [-email=<email>] [-username=<username>] [-id=<ID>] [-external-account-service-id=<serviceID> -external-account-service-type=<serviceType> [-external-account-account-id=<accountID>] [-external-account-login=<login>]] [-skip-unmatched-members]

User account matching

Matching a user account in Sourcegraph from an external system can be achieved in a few different ways: Sourcegraph User ID, Sourcegraph account email, Sourcegraph username or an explicit external-account mapping can be provided.

The matching order is as follows:

try Sourcegraph user ID
then try email
then try username
then try external-account

Example for external account matching with configured GitHub auth provider:

BASH
# Match a user with the account ID 123123123:
src teams members add \
  -team-name='engineering' \
  -external-account-service-id='https://github.com/' \
  -external-account-service-type='github' \
  -external-account-account-id='123123123'
# Match a user with the GitHub login handle alice:
src teams members add \
  -team-name='engineering' \
  -external-account-service-id='https://github.com/' \
  -external-account-service-type='github' \
  -external-account-login='alice'

Permissions in teams

For now, team permissions are based on membership. Read-only teams are only editable by site-admins. The creator of a team can always modify it, even if they are not a member of it.

Action	Site-admin	Regular user	Direct team member
Reading teams, metadata and members	🟢	🟢	🟢
Creating a new team	🟢	🟢	n/a
Creating a new child team	🟢	🔴	🟢
Creating a new read-only team	🟢	🔴	n/a
Updating team details/metadata	🟢	🔴	🟢
Deleting a team	🟢	🔴	🟢
Deleting a read-only team	🟢	🔴	🔴
Adding a member to a team	🟢	🔴	🟢
Removing a member from a team	🟢	🔴	🟢
Adding a member to a read-only team	🟢	🔴	🔴
Removing a member from a read-only team	🟢	🔴	🔴

Known limitations

Read-only teams can only be created by site-admins
Identity Provider / SCIM integrations are not available at the moment