Role Based Access Control
Video Tutorial: How to use Role Based Access Control
Manage user permissions in your organization and projects with Role Based Access Control (RBAC). This page gives an overview of RBAC, how to assign roles to users and groups, and how to create custom roles.
Overview
Semaphore uses an RBAC model to determine what actions users can take in organizations and projects.
An organization Admin or Owner must invite users via their GitHub or BitBucket accounts before they can access the Semaphore organization or any of the projects.
Role scopes
Semaphore manages roles on two levels:
- Organization: these roles allow users to perform various organizational actions. Users need to be added to the organization before they can access projects.
- Project: these roles give access to a project within the organization. Users need to have access to the repository connected to the project.
Roles can be gained in three ways:
- Direct: you can directly assign up to one organization role and one project role to the user
- Group: you can grant roles to groups. Group members gain the role assigned to the group
- Repository: users may gain project permissions based on their roles in the related repository (only on GitHub)
Permissions are additive
Permissions are additive. Users gaining permissions through multiple ways obtain the combined total of all permissions.
For example, let's say Pam has the admin role in the organization. This gives her unfettered access to all the projects in the organization. If Kevin gives her the reader role in one project, she is still effectively admin in that project. In other words, roles never subtract permissions.
Organization roles
Organization roles control what actions the users may perform in Semaphore. Users need to be added to the organization via their GitHub or BitBucket usernames before they can be granted a role. Only users who are part of the organization can log in to Semaphore.
The only exception is when a user is added via the Okta integration.
Member
Organization members can access the organization's homepage and the projects they are assigned to. They can't modify any settings.
This is the default role assigned when a user is added to the organization.
Among other actions, members can:
- View the organization's activity
- View and manage dashboards
- View and manage notifications
- Create projects
- View and manage secrets
- View and manage self-hosted agents
For the full list of member permissions, see organization roles.
Admin
Admins can modify settings within the organization or any of its projects. They do not have access to billing information, and they cannot change general organization details, such as the organization name and URL.
Only Admins and Owners can invite users to the organization.
In addition to the member permissions, admins can:
- View and manage organization settings
- View and manage the Okta integration
- Invite users to the organization
- Remove people from the organization
- View and manage billing plans
- View and manage pre-flight checks
- View and manage usage policy for secrets
For the full list of admin permissions, see organization roles.
Owner
The owner of the organization is the person that created it. An organization can have multiple owners. Owners have access to all functionalities within the organization and any of its projects. Only Admins and Owners can invite users to the organization.
For the full list of owner permissions, see organization roles.
To remove an owner, see how to remove an owner.
Organization groups
Your organization can have any number of groups. A group can have exactly one role directly assigned.
Groups can be added to the project and assigned exactly to project-level role. This grants every member of the group access to the project and grants them all the permissions inherited from the roles.
Project roles
Project roles control what actions the users may perform on the project. Project roles are assigned per project.
To grant a user access to a given project they need to:
- Be part of the Semaphore organization
- Have access to the related repository in GitHub or BitBucket
- Be granted access to the Semaphore project
The role given when a user is added to the project depends on their repository-level role. The following table shows how repository permissions map to project roles.
| GitHub repo role | BitBucket repo role | Semaphore project role |
|---|---|---|
| Pull | Read | Reader |
| Push | Write | Contributor |
| Admin | Admin | Contributor |
Reader
Readers can access the project page, and view workflows, their results, and job logs. They cannot make any modifications to the project.
Readers have:
- Read-only access to artifacts
- Read-only access to deployment targets (environment)
- Read-only access to test reports and flaky tests
- Read-only access to tasks
- View project notifications
- View project pre-flight checks
For the full list of reader permissions, see project roles.
Contributor
Contributors can view, rerun, change workflows, and SSH into jobs. Can promote and view insights, and run schedulers.
In addition to the reader permissions, contributors can:
- Delete the project
- Change project settings
- Manage project pre-flight checks
- Manage test reports and flaky tests
- Manage tasks
For the full list of contributor permissions, see project roles.
Admin
Admins have the authority to modify any setting within the projects, including the ability to add new individuals or remove them.
Custom roles
In addition to the pre-defined roles provided by Semaphore, you can create your own custom roles. Custom roles let you follow the principle of least privilege when managing using permissions.
To manage custom roles, see the following pages: