Overview

Merge’s Ticketing API surfaces Jira permissions through the Ticketing Permission common model. Permissions can apply at both the project level (Merge Collection) and the issue level (Merge Ticket).

To view a Jira issue with additional security restrictions, an end user must have access to both:

• the parent Collection (project), and

• the Ticket (issue).

Scopes

Merge maps Jira permissions for both admin and non-admin authenticated users, but the fidelity of Role mapping differs (details below).

Permission mapping (how Merge represents Jira access)

Object mapping

Merge maps Jira entities to Merge models like this:

• Collection → Jira Project

  • Project-level permissions are represented on the Collection.

• Ticket → Jira Work Item / Issue

  • Ticket-level permissions represent additional security restrictions beyond project access.

• User → Jira User

• Team → Jira Group

• Role → Jira roles (project roles and, for admin auth, application roles + “Any Logged In User”)

Jira project types (affects permissions behavior)

Jira has two project types with different permission models:

• Team-managed projects

  • Local project roles scoped to the project

  • Supports issue-level security restrictions by role, but Jira does not always expose which roles have access at the issue level (see limitations)

• Company-managed projects

  • Global roles and permission schemes

  • Supports more granular security levels on individual issues

Merge’s permission behavior

Implementation details that affect your product:

1) Permission effects you will see

Jira permissions are expressed in Merge with these effects:

• ALLOWED: access is explicitly granted to users, roles, or groups

• INHERITED: used on Ticket permissions only, meaning the Ticket’s access is identical to the parent Collection’s permissions (no extra restrictions)

2) Actions supported

Merge currently maps the VIEW action for Jira permissions. CREATE, EDIT, and DELETE are in progress, so some objects may not show those actions even if Jira would allow them.

3) Role mapping depends on admin vs non-admin auth

Non-admin authentication (simplified)

• One Role per Jira project role (regardless of team-managed vs company-managed).

• Users are only assigned to roles within company-managed projects when they are “default members” of the role in Jira.

• Application roles are not mapped.

Admin authentication (more complete)

• Team-managed project roles: Roles are created and populated from project settings.

• Company-managed project roles: Roles are created per company-managed project where assignable, and users are populated from project settings.

• Application roles: a Role is created per enabled Jira application (for example “jira-software”, “jira-servicedesk”), and users are assigned if they have access to that application.

• Special Role: “Any Logged In User”

  • All users are assigned this role, but it must be interpreted as “the currently logged-in user,” not “every user always has access.”

Practical takeaway:

• When you evaluate permissions, you must interpret Role holders in the context of Permission objects, not by role membership alone.

How to interpret permissions in your product

Collection (project) access

A Jira project is viewable when a Collection Permission grants VIEW to at least one of:

• a Role (project role, application role, or “Any Logged In User”)

• a Team (Jira group)

• specific Users

Ticket (issue) access

A Jira issue is viewable when:

1. the user has access to the parent Collection (project), and

2. the Ticket permissions either:

• are INHERITED (meaning project access is sufficient), or

• include an ALLOWED grant that includes the user via role, group, or explicit user permission.

Current limitations and important nuances

1) “Browse Projects” permission bug (company-managed projects)

There is a known Jira bug: if “Browse Projects” is granted to certain holder types (User custom field, Group custom field, Reporter, Assignee), Jira effectively grants access to “any logged in user,” and Jira’s docs are unclear on intended behavior.

As a result, Merge maps the “Any Logged In User” Role for the Collection Permission in these cases.

2) Team-managed issue security restrictions may be unmappable

For team-managed projects, when an issue has additional security restrictions, Jira’s API may not return which roles have access. In these cases, Merge cannot map specific role-based permissions at the ticket level, and the ticket may have no Permission objects (not INHERITED).

3) Permission scheme changes may not immediately reflect on existing issues

If a security scheme changes who can access a given security level, existing tickets may not reflect the new permissions until they are updated in Jira, because the issue “updated” timestamp does not change and there are no supporting audit log/webhook events for scheme changes.

Example: Tickets A, B, and C in Project 1 have security level "high". According to the work item security scheme assigned to Project 1, "high" is accessible to any logged-in user. If the security scheme is later changed to restrict "high" to only a specific user, we cannot capture that change without a full resync of every ticket.

We are evaluating different solutions to capture this more frequently without requiring a full resync of every ticket.

Best practices

1. Check both Collection and Ticket permissions: users need both levels for secured issues.

2. Consider project type: team-managed vs company-managed behave differently.

3. Treat INHERITED on a Ticket as “same as project access.”

4. Account for timing: scheme-level changes may not surface until an issue is updated.