Explicit permissions API

Sourcegraph's GraphQL API allows users to explicitly set repository permissions. This is an alternative to other mechanisms, which involve directly talking to the code host.

Permissions mechanisms in parallel

Up to Sourcegraph 5.0

Experimental Sourcegraph 5.0+

If you want to use explicit permissions API alongside synced permissions, read section permission mechanisms in parallel here.

Recommendations

We only recommend to use explicit permissions API in cases, where the other methods are not possible or effective. E.g. if a code host does not support permission syncing/webhooks or if it would take an unreasonable amount of resources/time to sync permissions from the code host.

It's also a good idea to use explicit permissions API if the source of truth for the codehost permissions is already defined in some external system, e.g. LDAP group membership. In that case, it might be less resource intensive to sync the permissions from external source of truth directly via a periodically running routine.

SLA

Sourcegraph SLA is, that p95 of write requests to the explicit permissions API will be resolved within 10 seconds.

Sourcegraph does not provide SLA for how fresh the permissions are, since the data is provided as is to the API.

Disadvantages

It is important to note, that when using explicit permissions API, the permissions are written to the database as provided, without further verification that such permissions do exist on the code host side.

Keeping the permissions in sync and fresh is the responsibility of the site admins.

Configuration

To enable the permissions API, add the following to the site configuration:

"permissions.userMapping": {
    "enabled": true,
    "bindID": "username"
}

The bindID value specifies how to uniquely identify users when setting permissions:

• username: You can set permissions for users by specifying their Sourcegraph usernames. Using usernames is preferred, as usernames are required to be unique for each user.
• email: You can set permissions for users by specifying their email addresses (which must be verified emails associated with their Sourcegraph user account). This method can lead to unexpected results if there are multiple Sourcegraph user accounts with the same verified email address.

After you enable the permissions API, you must set permissions to allow users to view repositories (site admins bypass all permissions checks and can always view all repositories).

Setting a repository as unrestricted

Sometimes it can be useful to mark a repository as unrestricted, meaning that it is available to all Sourcegraph users. This can be done with the setRepositoryPermissionsUnrestricted mutation. Marking a repository as unrestricted will disregard any previously set explicit or synced permissions. Setting unrestricted back to false will restore the previous behaviour.

For example:

mutation {
  setRepositoryPermissionsUnrestricted(repositories: ["<repo ID>", "<repo ID>", "<repo ID>"], unrestricted: true)
}

Setting repository permissions for users

Setting the permissions for a user can be accomplished with 2 GraphQL API calls.

First, obtain the ID of the repository from its name:

query {
  repository(name: "github.com/owner/repo") {
    id
  }
}

Next, set the list of users allowed to view the repository:

mutation {
  setRepositoryPermissionsForUsers(
    repository: "<repo ID>",
    userPermissions: [
      { bindID: "alice" },
      { bindID: "bob" },
    ]) {
    alwaysNil
  }
}

Now, only the users specified in the userPermissions parameter will be allowed to view the repository. Sourcegraph automatically enforces these permissions for all operations. (Site admins bypass all permissions checks by default. See the Site administrators section)

You can call setRepositoryPermissionsForUsers repeatedly to set permissions for each repository, and whenever you want to change the list of authorized users.

Listing a user's authorized repositories

You may query the set of repositories visible to a particular user with the authorizedUserRepositories GraphQL API query, which accepts a username or email parameter to specify the user:

query {
  authorizedUserRepositories(username: "alice", first: 100) {
    nodes {
      name
    }
    totalCount
  }
}