Practical JIRA Administration

Chapter 1. Groups Versus Roles

Overview

The difference between JIRA groups and JIRA project roles seems to confuse many JIRA administrators. This chapter explains the differences and what each one is good for.

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:

1. Create a new permission scheme with a description something like john.smith can change Reporter.

2. Next, add the john.smith user to the appropriate Modify Reporter permission entry in the new permission scheme.

3. Change the appropriate JIRA project to use the new permission scheme.

You could also do the same thing with a group:

1. Define a new JIRA group named Can Modify Reporters.

2. Add the user john.smith to the new group.

3. Create a new permission scheme with a description something like Added an extra group of users that can change Reporter.

4. Add the group (instead of the user) to the appropriate Modify Reporter permission entry in the new permission scheme.

5. 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.

Scaling

If you want john.smith to be able to edit the Reporter field in some projects, and also allow a different user, 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.

Updating

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.

Project Roles

What was needed to avoid these problems with JIRA groups was another level of indirection,¹ and that’s exactly what JIRA project roles are. Figure 1-1 shows the basic idea.

Figure 1-1. JIRA project roles

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.

Figure 1-2. JIRA default roles and their memberships

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.

To put all that another way:

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 Administrators project role.

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 the 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 users.

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.

Tip

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.

Tip

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.

Summary

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.

Tip

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.

Further Reading

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 subroutine.