Work with Permission Schemes

Permission schemes are a collection of PermissionGrant, which govern whether a user can do a particular action in any given project.

Within Jira, each project is associated with one permission scheme. However, a permission scheme can be associated with multiple projects. If you change a permission scheme you will affect all projects that use it. Learn more about permission schemes in Atlassian's documentation.

This page is specific to project permission schemes. If you want to modify projects see the Work with Projects page.

Retrieving a project's permission scheme

You can get a project's permission scheme as follows:

            def project = Projects.getByKey('SR')   
            def permissionScheme = project.permissionScheme

Modifying permission schemes

Add permissions to a permission scheme

You can add permissions to a permission scheme as follows:

            import com.atlassian.jira.permission.JiraPermissionHolderType
            import com.atlassian.jira.permission.ProjectPermissions
            
            // gives any logged-in user Browse permission - note the empty string
            permissionScheme.addPermission(ProjectPermissions.BROWSE_PROJECTS, JiraPermissionHolderType.APPLICATION_ROLE, '')

            // gives the reporter Delete permission
            permissionScheme.addPermission(ProjectPermissions.DELETE_ISSUES, JiraPermissionHolderType.REPORTER)  

            // gives the jira-users group Edit permission 
            permissionScheme.addPermission(ProjectPermissions.EDIT_ISSUES, JiraPermissionHolderType.GROUP, 'jira-users')

Image showing how you add permissions to a project schema

When adding user or group custom fields to the permission scheme remember to use the custom field ID, not the custom field name. For example:

            import com.atlassian.jira.permission.JiraPermissionHolderType
            import com.atlassian.jira.permission.ProjectPermissions

            permissionScheme.addPermission(ProjectPermissions.MANAGE_WATCHERS, JiraPermissionHolderType.GROUP_CUSTOM_FIELD, 'customfield_12345')

Completions

If completions are not visible when writing a script, you can trigger them using Ctrl + space.

Use completions on ProjectPermissions to see the different permissions available, these correspond to the permissions available to you when managing project permissions in Jira.

Image showing project completions

Use completions on JiraPermissionHolderType to see different permission holder types. JiraPermissionHolderType completions correspond to the radio buttons in the Grant permission dialog box in Jira.

Image showing jira permission completions

Remove permissions from a permission scheme

You can remove permissions from a permission scheme in a similar way to how you add permissions.

            import com.atlassian.jira.permission.JiraPermissionHolderType
            import com.atlassian.jira.permission.ProjectPermissions
            
            // removes any logged-in user Browse permission - note the empty string
            permissionScheme.removePermission(ProjectPermissions.BROWSE_PROJECTS, JiraPermissionHolderType.APPLICATION_ROLE, '')

            // removes the reporter Delete permission
            permissionScheme.removePermission(ProjectPermissions.DELETE_ISSUES, JiraPermissionHolderType.REPORTER)  

            // removes the jira-users group Edit permission 
            permissionScheme.removePermission(ProjectPermissions.EDIT_ISSUES, JiraPermissionHolderType.GROUP, 'jira-users')

Image showing how you remove permissions from a project schema

You can remove all permissions of a particular type using clearPermissions:

            import com.atlassian.jira.security.plugin.ProjectPermissionKey

            permissionScheme.clearPermissions(new ProjectPermissionKey('MANAGE_SPRINTS_PERMISSION'))

Checking permissions

You can check if a permission is already granted as follows:

            import com.atlassian.jira.permission.JiraPermissionHolderType
            import com.atlassian.jira.permission.ProjectPermissions

            // does the "reporter" have "Edit Issue" permission            
            permissionScheme.hasPermission(ProjectPermissions.EDIT_ISSUES, JiraPermissionHolderType.REPORTER)

            // does the "jira-users" group have "Browse" permission            
            permissionScheme.hasPermission(ProjectPermissions.BROWSE_PROJECTS, JiraPermissionHolderType.GROUP, 'jira-users')

Image showing how to check permissions using HAPI

Alternately, you can get all permission grants for a specific permission type. In the following example we're getting all the permission grants for the Browse Projects project permission type.

            import com.atlassian.jira.permission.ProjectPermissions
            
            permissionScheme.getPermissions(ProjectPermissions.BROWSE_PROJECTS)

You can also get all permissions grants for a specific permission type AND specific permission holder type. In the following example we're getting all the permission grants for Group permission holders with the Browse Projects project permission type.

            import com.atlassian.jira.permission.JiraPermissionHolderType
            import com.atlassian.jira.permission.ProjectPermissions
            
            permissionScheme.getPermissions(ProjectPermissions.BROWSE_PROJECTS, JiraPermissionHolderType.GROUP)