Chapter 1. Groups Versus Roles
JIRA originally just had users and groups of users, and no project roles. Groups were pretty powerful—wherever you could do something with a user, you could generally use a group instead.
For instance, if you wanted to allow a specific user
john.smith to change the Reporter field in a
project’s issues, you could:
Create a new permission scheme with a description something like
john.smithcan change Reporter.
Next, add the
john.smithuser to the appropriate Modify Reporter permission entry in the new permission scheme.
Change the appropriate JIRA project to use the new permission scheme.
You could also do the same thing with a group:
Define a new JIRA group named
Can Modify Reporters.
Add the user
john.smithto the new group.
Create a new permission scheme with a description something like
Added an extra group of users that can change Reporter.
Add the group (instead of the user) to the appropriate Modify Reporter permission entry in the new permission scheme.
Just as before, change the appropriate JIRA project to use the new permission scheme.
Both of these approaches now allow
john.smith to change the Reporter field. So far
so good, but there are two main problems with using JIRA groups like this:
scaling and updating.
If you want
john.smith to be
able to edit the Reporter field in some projects, and also allow a
jane.bloggs, to do
the same thing in other projects, then you have to create two permission
schemes, one for each user being granted this permission. If you then
decide that they are both allowed to edit the Reporter in some shared
projects, then you need a third permission scheme.
With lots of users, this leads to an explosion in the number of
permission schemes (and any other JIRA scheme that supports groups).
Keeping track of the difference between each of these permission schemes is tedious and error-prone, even with the scheme comparison tools (Administration→Scheme Tools), which are themselves deprecated in JIRA 6.4.
As time passes, users will likely need to be part of different JIRA groups. Only JIRA administrators can change the membership of JIRA groups. However project leads are allowed to make changes to project roles, and project leads usually know which project roles a user should currently be part of. Using project roles means fewer tasks for JIRA administrators.
JIRA has three default project roles: Administrators, Developers, and Users. The current members of these roles for each project can be seen at Administration→Projects: click on the project name, then Roles.
The number and names of the roles can be changed at Administration→User management→Roles, but for now let’s stick with the three default roles. Every JIRA project has the same set of project roles all the time. The default members of each role for new projects are shown in Figure 1-2. Note that the project lead is not a default member of the Administrators role and has to be explicitly added.
For each role in every project, a JIRA administrator or a project administrator can define who plays that role by adding or removing a user or a group for the role.
For example, you could add an individual contractor using JIRA to the Users role for only the projects they need to work with. For such JIRA instances, I usually create a new JIRA group named something like “my-company-name-staff” and then replace the “jira-users” group with the new group throughout JIRA. I then create a JIRA group for each set of contractors and add that group to the appropriate project roles for select JIRA projects (and also to the “JIRA Users” permission at Administration→System→Global permissions).
Once you’ve chosen who plays each role for each project, you can use the roles in your schemes. For instance, when you look at the default permission scheme you’ll see that all of the permissions are granted to project roles, not directly to users or groups. The significant thing about roles is that they can be changed for each project by people who are in the Administrators role but are not JIRA administrators. These people can now create versions and components for their project without needing to change the underlying configuration of JIRA or needing to be JIRA administrators.
- Who can change a project’s versions and components?
The users who have the Administer Projects permission.
- Which users have the Administer Projects permission?
Check the specific permission scheme, but it’s usually only people in the
- Which users have the Administrators project role?
Members of the jira-administrators group and anyone else that you add to that role for a project.
- Who can change other parts of JIRA’s configuration?
Only members of the jira-administrators group, not the users who have the Administrators project. Project administrators can’t change workflows, for example.
Creating a New Project Role
Another way to understand what’s going on here is to create a new
project role. Let’s say that for some reason, we want to allow the
technical publications (
Tech Pubs) users assigned to each
project to modify the Reporter of an issue.
The default permission scheme already allows users with an Administrator role in a project to modify the Reporter of an issue. But we don’t want to allow the Tech Pubs user to administer the whole project: we just want to give them that one specific permission.
We can create a new role Documentation, at
Administration→User management→Roles. We can also add our Tech Pubs lead
bobby.jones as a default member in the
Users column under
Manage Default Users of
the new project role so that he will be in the Documentation role for all
new projects by default.
Now every JIRA project has this new role, since you can’t add a
new project role just for one JIRA project. When a new JIRA
project is created, it will have
bobby.jones user in the
Documentation role for the project. For existing projects, we can
manually add the appropriate Tech Pubs user (or group) to the
Documentation role for each project. Once the users for this role
have been added, we can edit the appropriate permission schemes
and add the Documentation role to the Modify Reporter permission
entry. The permission scheme now checks which users are in
the role for each project, rather than
looking at a fixed list of users or groups of
If the Tech Pubs person changes for the project, then the people in the project role Administrator can change the members of the Documentation role for just that project. There is no need to ask a JIRA administrator to make the changes.
An example of a good description for a newly created role is “This new project role is for identifying Facilities staff in non-Facilities projects.” Creating a wiki page that describes the intended purpose of each new role is another good idea.
For more information about using project roles to control which users can view which projects, see “Hiding Projects from Users”.
From the other direction, you can also see which roles an individual user has in all the JIRA projects: go to Administration→User management→Users, find the user, and click on Project Roles.
The easiest way to allow everyone to see the members of each role for a JIRA project is to install the Project Role Tab add-on. This add-on allows JIRA administrators to tell their users to contact the project administrators for certain changes.
Not Creating New Project Roles
Sometimes I see JIRA instances where roles have been treated like groups. This results in many roles being created, but many of these only make sense in a few projects. For instance, if you create a new role named Operations and then have a JIRA project for tracking job applications, there may be no obvious use for Operations and job applications. The best approach is to keep the number of roles as small and generic as possible. Some useful examples of names for extra roles are: Creators, Approvers, Managers, Workers, Testers and Schedulers. These names are generic and apply to more than just software development.
Another configuration problem I see is using user names in the default memberships of roles. What happens is that every new project has the user name set for the role, but when the user leaves, every project has to be modified to change the role. This is a good argument for using only groups as default role members.
One mistake I’ve seen have some serious consequences is using a project role in a notification scheme. This can happen when you want to allow project administrators to send specific users an email when an issue is created in their project. It’s easy to create a project role such as Notify on All Create Issue and add it to the notification scheme. The problem is that a unknowing project administrator can add a large group such as jira-users to the project role and then every single person in jira-users will receive email when a new issue is created. In a large organization this can be thousands of users being spammed each time. I recommend not using project roles in notification schemes if possible.
You should only create a new project role if you are going to use it in a scheme or workflow, and if it applies to all your JIRA projects.
JIRA groups are made up of JIRA users and can only be changed by JIRA administrators. But JIRA project roles are made up of JIRA users and JIRA groups and can be changed per project by project administrators. Project administrators are all the users in the Administrators role for a JIRA project.
Should I use a group or a project role?
If you want to refer to the same set of more than about six users across multiple projects, use a group. Remember that group membership has to be maintained to be useful If you want to refer to a set of users that is potentially different per project, use a project role. Also, don’t add new roles without considering whether the existing ones can be used in the permission scheme to accomplish what you are trying to do.
http://confluence.atlassian.com/display/JIRA/Managing+Groups discusses JIRA groups in general.
http://confluence.atlassian.com/display/JIRA/Managing+Project+Roles discusses JIRA Project Roles specifically.
Some of the background information to this chapter can be found at https://confluence.atlassian.com/display/JIRA063/Migrating+User+Groups+to+Project+Roles, along with the documentation for the JIRA Scheme Comparison Tools. Unfortunately, the scheme tools only work with Permission and Notification Schemes, and they are deprecated as of JIRA 6.4.
Holger Schimanski’s Project Role Tab add-on is an good way to allow everyone to see who is in each role in a JIRA project. It currently costs nothing and the source code is freely available, though it is not a supported add-on.
All problems in computer science can be solved by another
level of indirection. — David Wheeler, the inventor of the