Overview

Merge’s Linear integration syncs Teams, Projects, Cycles, Issues, and Customer Needs. Linear permissions are primarily Team-based, and Merge represents that access using Merge’s Collections, Roles, and Permissions models.

This guide explains the key permission behaviors you should plan for when building with Merge + Linear.

Scopes

Merge only needs read scope to sync data from Linear.

Permission mapping (how Merge represents Linear access)

Object mapping

Merge maps Linear entities to Merge models like this:

• Ticket → Linear Issue and Customer Need

  • These are differentiated by ticket.ticket_type.

• Collection → Linear Team, Project, Cycle

  • Teams are mapped to Collections so access control can be expressed consistently across Teams, Projects, and Cycles.

• Role → Linear workspace roles

  • Linear roles are built-in (for example: Admin, Member, Guest).

How Linear access works (high-level)

In Linear:

• Issues, Customer Needs, Projects, and Cycles are associated with a Team, and access generally follows the Team.

• Some users may have visibility to a specific Issue based on being directly involved (for example, as the creator, assignee, or a subscriber).

Merge’s permission behavior

Implementation details that affect your product:

1) Collection access_level

Merge sets Collection access_level to PRIVATE for all Linear Collections (Teams, Projects, Cycles).

What this means for your product:

• You should treat “public vs private” as something expressed through Permissions, not via a Collection’s access_level value.

2) Ticket access_level

Merge sets Ticket access_level to COLLECTION for Linear Tickets (Issues, Customer Needs).

What this means for your product:

• Ticket visibility should be enforced based on the Ticket’s Collection context (the Team), plus any additional user-specific grants described below.

3) Permission effects you will see

Merge represents access using Permission objects that may have one of these behaviors:

• ALLOWED: direct access is granted to roles, teams, or users.

• INHERIT: access is inherited from another Collection (commonly used for Projects and Tickets inheriting from Teams).

How Merge builds permissions

Merge represents access using Permission objects that grant access based on:

• Roles (applied_to_roles)

• Team membership (applied_to_teams)

• Specific users (applied_to_users)

• Inheritance from other Collections (applied_to_collections when effect = INHERIT)

Permissions by Linear entity type

Teams (Collections)

Public teams

Merge represents access to a public Team using two explicit permission grants:

1. Admins and Members

• effect = ALLOWED

• applied_to_roles = [Admin, Member]

2. Guests (only if they belong to the Team)

• effect = ALLOWED

• applied_to_roles = [Guest]

• applied_to_teams = [that Team]

Practical takeaway:

• If you are showing “who can see this Team,” evaluate both:

  • role-based grants, and

  • team-membership-based grants.

Private teams

Merge represents access to a private Team strictly through Team membership:

• effect = ALLOWED

• applied_to_teams = [that Team]

Practical takeaway:

• A user must be a member of the private team to see the team and anything inside it.

Sub-teams

Sub-teams do not inherit access from their parent team.

Practical takeaway:

• Do not assume parent team membership implies sub-team visibility (or vice versa).

Projects (Collections)

Projects can be shared across multiple teams and can also have explicit Project Members. Merge represents Project access using two permission components:

1. Inherited access from each Team the Project is shared with

• effect = INHERIT

• applied_to_collections = [Team Collection(s) the Project is shared with]

2. Direct user access for Project Members

• effect = ALLOWED

• applied_to_users = [Project members]

Practical takeaways:

• A Project can be visible to users via Team inheritance even if they are not a Project Member.

• A user can be a Project Member and still not see every Issue in the Project if they cannot access the Issue’s Team (Issues remain Team-scoped).

• The same user may appear in multiple permission grants (for example, inherited + explicit).

Cycles (Collections)

Cycles belong to a single Team.

Merge represents Cycle access similarly to Team access, using the Team’s public vs private behavior.

• Cycle in a public team

  • ALLOWED via applied_to_roles = [Admin, Member]

  • ALLOWED for Guests only if they belong to the Team via applied_to_roles = [Guest] + applied_to_teams = [Team]

• Cycle in a private team

  • ALLOWED via applied_to_teams = [Team]

Practical takeaway:

• Cycle access is Team-driven.

Issues (Tickets)

Merge represents Issue access using two components:

1. Inherited access from the Issue’s Team Collection

• effect = INHERIT

• applied_to_collections = [Issue’s Team Collection]

2. Direct user access for Issue participants

• effect = ALLOWED

• applied_to_users = [creator, assignee, subscribers]

Practical takeaway:

• Even if someone cannot access the Team broadly, Linear may allow Issue visibility based on direct involvement, and Merge represents that with user-specific permissions.

Customer Needs (Tickets)

Customer Needs are related to Issues. Merge represents access such that:

• Users who can access the related Issue can access the Customer Need.

• The Customer Need creator can also access the Customer Need.

Practical takeaway:

• Customer Need visibility is effectively “Issue visibility, plus creator.”

Common scenarios to plan for

“Why can’t a user see an Issue that is in a Project they can see?”

In Linear, Issues belong to a Team. Project visibility does not override Team visibility for Issues. Merge models this by tying Issue access to the Issue’s Team Collection (plus participant access).

“Why can’t a user see Issues in a sub-team if they are in the parent team?”

Sub-team access is not inherited. Users need access to the specific sub-team.