Skip to content

Role-based access control#

The BSR has two role axes that together decide what any user can do:

  • Organization roles apply to a user’s membership in an organization. They control access to the organization itself: settings, members, the ability to create or delete resources.
  • Resource roles apply per resource (repositories and plugins) and control read/write access to that specific resource.

Most permissions resolve from the combination of the two: an organization member’s resource access is shaped by both their organization role and the resource’s own role assignments.

For the UI path to assign roles, see Manage organizations.

Organization roles#

Every user who’s a member of an organization carries one organization role. The role grants direct organization-level capabilities and seeds an implicit role on the organization’s resources. Members can’t change their own organization role; only an Owner or Admin can.

Member#

  • Can view the organization and its members.
  • On organization-owned resources, gets the implicit role described in Resource roles.

Writer#

  • Can view the organization and its members.
  • Can create new resources (repositories and plugins).
  • Has Write on every organization resource (existing or newly created), regardless of the organization’s base resource role.

This role fits CI workflows. For example, set the base resource role for repositories to Read so most members get read-only access, then provision a bot user with the Writer organization role to push on merge.

Admin#

  • Can modify organization settings, including base resource roles.
  • Can add and delete resources (repositories and plugins).
  • Can manage member roles, except Owner. Only an Owner can change another user’s role to or from Owner.

Owner#

Every organization has at least one Owner, and can have more.

  • Has unrestricted access to the organization, its settings, and every resource it owns.
  • Can add and delete resources, manage every other member’s role (including Owner), and delete the organization. Resource deletion has to happen first; the organization can’t be deleted while it owns resources.

Resource roles#

A resource role applies to a single repository or plugin. Four values exist:

  • Read: read the resource and import it as a dependency.
  • Limited Write: write to non-default labels of the resource, but not the default label.
  • Write: write to every label and create new ones.
  • Admin: administer the resource, including managing member access, updating settings, and deleting it.

Explicit and implicit#

A user can hold a resource role two ways:

  • Explicit: assigned directly to that user on that resource (or held by virtue of being the resource’s owner).
  • Implicit: derived from the user’s organization role and the organization’s base resource role (see below).

When both exist, the higher-privilege role wins at runtime. An explicit role can’t be set below the implicit one; setting an explicit role only makes sense to grant more than the implicit baseline.

Base resource roles#

Every organization sets a base resource role per resource type, which becomes the implicit role for every Member of the organization on every resource of that type:

Resource type Default base role Configurable values Editable?
Repository Limited Write Read, Limited Write, Write, Admin Yes
Plugin Read (fixed) No

The plugin base role is fixed at Read. The organization-settings surface only exposes the repository base role for editing today.

Writer and higher organization roles override the base: Writer always gets Write on every resource regardless of the base, Admin always gets Admin, and Owner always gets full access.

To assign a non-default explicit role to a single user on a single repository, see Change repository access.

Example#

An organization sets the repository base role to Read. A user is a Member of that organization. They open repository acme/petapis:

  • Default state: their implicit role on acme/petapis is Read. They can read and depend on the repo but can’t push.
  • Granted an explicit Write on acme/petapis: their effective role on that repository is Write. The implicit Read baseline still applies to other repositories.
  • Promoted to Writer at the organization level: their implicit role on every repository (including acme/petapis) becomes Write, regardless of the base role. The earlier explicit Write is now redundant.
  • Promoted to Owner: full access everywhere; no per-resource assignments matter.