Roles
The eight default roles every team starts with, how to create and edit custom roles, the permission catalogue, and the rules on deleting a role.
By the end of this page you will know what the default roles are for, how to shape a role of your own from the permission catalogue, and why a role's code never changes.
A role is a named set of permissions inside one team. Every member holds exactly one role per team; the owner holds none, because the owner may do everything. A permission is written as entity:action, such as work-item:create or release:approve, and a role is simply the list of permissions it grants.
Before you begin
| You need | Why |
|---|---|
role:view-any | To see a team's roles on the page. The owner always can. |
role:create | To create a role in a team. |
role:update | To rename, describe or re-permission a role. |
| To own the team | To delete a custom role someone else created. The person who created it may delete it too. |
The default roles
Every team is seeded with these roles, and a project can mirror them with per-project overrides:
| Role | Code | Intended for |
|---|---|---|
| Admin | admin | Everything the owner may do inside the team, short of renaming or deleting it. |
| Project Manager | project_manager | Running projects end to end: planning, approvals, sprints, releases and maintenance, without the workspace plumbing. |
| Business Analyst | business_analyst | The planning artefacts in full (epics, stories, requirements, rules, use cases, personas, glossary), reading elsewhere. |
| Developer | developer | The backlog, board, code links and time logs in full; planning read; tests read and execute; releases read. |
| QA Engineer | qa_engineer | Test management and defects in full; planning read; releases read, with sign-off on acceptance runs. |
| Release Manager | release_manager | Releases, deployments and environments in full, reading elsewhere. |
| Viewer | viewer | Reads everything, changes nothing. |
| Guest | guest | No team permissions at all. A guest's access comes from the project membership their invitation created. |
The default roles can be re-permissioned to suit your team, but never deleted: the project roles are built on them.
Re-running the workspace seeder after the permission catalogue grows brings every team's default roles up to date without duplicating them; a custom role is left exactly as you made it.
Where roles live
Open Account Settings → Roles. The page lists the roles of every team where your role lets you view them, by name:
| Column | What it shows |
|---|---|
| Role | The name, the code in small type, a Default badge on a seeded role, and the description beneath. |
| Team | Which team the role belongs to, since the page spans your teams. |
| Permissions | How many permissions the role carries. |
| Row menu | Edit when you may update roles in that team, Delete when the role is custom and yours to delete. |
Create a role
- Press Create a Role. The button appears when at least one of your teams lets you create roles.
- Pick the Team the role belongs to.
- Type a Name, a Code and, if useful, a Description.
- Tick the Permissions the role should grant. They are grouped by entity, one group per kind of thing, with the five common actions and the named actions each entity has.
- Press Create.
The code must be unique within the team; a second role with the same code is refused with a message. Once created, the code is fixed.
Edit a role
- Open the role's row menu and choose Edit. The flyout opens with the code shown but not editable.
- Change the Name, the Description or the Permissions, and press Save.
- Members who hold the role gain or lose the permissions the next time they load a page.
Saving without changing anything writes and announces nothing.
Delete a role
- Open the row menu of a custom role and choose Delete.
- Press Delete Role in the confirmation.
- Members who held the role keep their membership but lose the permissions it granted; move them to another role from the members page.
A default role cannot be deleted. A custom role can be deleted by the person who created it or by the team's owner, and by nobody else: belonging to a team is not a licence to dismantle how everyone else in it is permissioned.
The permission catalogue
Permissions follow one grammar, entity:action. Most entities carry the five common actions:
| Action | Lets a member |
|---|---|
view-any | Open the list of that entity. |
view | Open one item. |
create | Add one. |
update | Change one. |
delete | Remove one. |
Some entities add named actions for the moments that matter: epic:approve, work-item:transition, sprint:start, release:publish, incident:command, team-member:invite, and so on. The editor shows the whole catalogue, including entities whose pages are still to land, so a role you shape today keeps meaning the same thing as the product grows.
All the fields
What happens next
| Action | Event announced | Payload |
|---|---|---|
| Create a role | role.created | The code, the name, the full permission list, the role id and the team. |
| Edit a role | role.updated | Field-by-field changes: the name, the description and the permission sets before and after. |
| Delete a role | role.deleted | The code, the name, the role id and the team. |
Permissions
| Action | Who may do it |
|---|---|
| See a team's roles | The owner, or a member with role:view-any |
| Create a role | The owner, or a member with role:create |
| Edit a role | The owner, or a member with role:update |
| Delete a custom role | The owner, or the member who created it |
| Delete a default role | Nobody |
Frequently asked
Related
- Members and guests: assign a role when inviting, or change one later.
- Groups: permissions granted on top of a role.
- Teams: roles belong to a team.
How is this guide?
Last updated on
Members and Guests
Invite a colleague with a role or a client as a guest of one project, change a member's role, remove someone, and manage the invitations still waiting.
Ability Reference
The complete list of permissions a role or a group can grant, what each entity covers, and a plain sentence on what a member holding each permission can do.