Short definition
A project role in Jira is a named bucket of users and groups that's defined globally but populated per project. Default roles include Administrators, Developers, and Users; admins can add more (e.g., QA, Stakeholders). Project roles are referenced from permission schemes, notification schemes, and workflow conditions - so adding a user to a role grants the access that role's permissions describe.
What roles are for
Project roles let admins express “the people in this project who do that job” without hard-coding specific usernames into permission and notification schemes. The schemes reference roles abstractly; the project decides who fills each role.
This is why roles scale better than direct user references. A permission scheme that grants Edit Issues to “Project Role: Developers” works in any project that uses the scheme - and each project can have its own list of developers without modifying the scheme.
Default roles
Out of the box Jira ships with three project roles:
- Administrators - project-level admin (manage components, versions, role membership).
- Developers - the people doing the work. Default audience for most edit permissions.
- Users - read access. Customers, observers, browse-only users.
Most installations add a few more over time: QA, Product Owner, Stakeholder, Release Manager. Each custom role is global (every project can populate it) but the membership is per-project.
Where roles are referenced
Roles appear in several configuration surfaces:
- Permission schemes - grant or deny actions to role members. “Edit Issues -> Project Role: Developers.”
- Notification schemes - send event notifications to role members. “Issue Created -> Notify: Project Role: Stakeholders.”
- Workflow conditions - restrict transitions to role members. “Only Project Role: Release Manager can transition to Released.”
- Issue security schemes - control which roles can see issues at a given security level.
The same role can be referenced from all of these simultaneously, so adding a user to it grants the combined effect across the project.
Roles vs. groups
A common confusion. The simplest framing:
- Group: this user is X across the whole Jira instance.
- Role: this user is X in this specific project.
A user in the jira-developers group is a developer everywhere. A user in the Developers project
role in Project A is a developer in Project A only - and can be a Stakeholder in Project B, a User in
Project C, etc.
For instance-wide policies, use groups. For per-project access, use roles. Most non-trivial Jira configs use both: groups for the broad identity, roles for the per-project nuance.
Common pitfalls
Two recurring issues:
- Empty roles. A scheme grants access to a role that has nobody in it in some projects, so the permission silently doesn’t apply. Audit role membership across projects when adding a new role- based permission.
- Direct user/group references in schemes. Bypasses the role abstraction and forces scheme edits for every personnel change. If you find yourself editing a scheme to add a user, the right fix is usually to convert that scheme entry to reference a role and add the user to the role.
Common questions
What is a project role in Jira?
A project role in Jira is a named bucket of users and groups that's defined globally but populated per project. Default roles include Administrators, Developers, and Users; admins can add more (e.g., QA, Stakeholders). Project roles are referenced from permission schemes, notification schemes, and workflow conditions - so adding a user to a role grants the access that role's permissions describe.
How are project roles different from groups?
Groups are global directory entities - a user is in a group regardless of project. Roles are project-scoped memberships - a user can be a Developer in Project A and a Stakeholder in Project B. Groups suit cross-project membership (e.g., 'jira-administrators'); roles suit per-project access. Most schemes reference roles, not groups directly.
How do I add a user to a project role?
Go to the project -> Project settings -> People (or Users and roles, depending on Jira version). Find the role; add the user. Effect is immediate. To add via REST: `POST /rest/api/2/project/{key}/role/{roleId}` with the user account ID. Bulk updates are usually done via the UI or a CSV-driven script against the API.
Can a custom project role be added?
Yes. In global admin -> System -> Project roles, add a new role with a name and description. The role then appears in every project's role list, empty until someone is added. Permission schemes and notification schemes can reference the new role immediately. Removing a custom role requires it to be unreferenced from all schemes first.