Linear

A card linked to a Linear issue shares its title, description, status, estimate, and parent with it, edited from either side. One admin connects the Linear workspace, and nobody else signs in.

This page is written for the Linear admin who is deciding whether to approve the install. It says exactly what the app can reach, what it changes, and how to take it back out.

At a glance

Topic	Details
Connects	A board to one Linear team
Authorization	One workspace-wide grant. A CardBoard admin approves CardBoard as an app on your Linear workspace, and every member works through it.
Fields that sync	Title, description, status, estimate, parent (sub-issues)
Updates from Linear	The app’s webhook, within seconds
Plan	Pro, Team, or Enterprise
Directory listing	Not listed yet. Connect from CardBoard.

What syncs

Card field	Direction	Notes
Title	Both ways
Description	Both ways	Both sides store Markdown, so formatting passes through unchanged.
Status	Both ways	Uses each team’s own workflow states.
Estimate	Both ways	The card’s size, on the team’s own estimate scale. A size that isn’t on the scale, or a team with estimates turned off, is skipped and the card tells you why. T-shirt sizes come across as their point values, so M is 3.
Parent	Both ways	Nesting a card under another linked card makes its issue a sub-issue. See Sub-issues.
Link to the card	CardBoard to Linear	Every linked issue gets a “CardBoard Card” attachment that opens the card.
Issue type	Set when created	Linear has one issue type.
Assignee, priority, labels, comments	Not synced
Position, slice, connections between cards, color, shape, reactions	Never	Position belongs to the map. Rearrange freely.

Statuses. The card’s status menu lists the connected team’s own workflow states, so you pick the names your team already uses. There’s nothing to map by hand.

When an issue changes in Linear, the linked card updates on the map within seconds. If an issue is deleted in Linear, the card stays on the map and is marked as deleted in Linear.

Sub-issues

A card’s parent on the map and an issue’s parent in Linear are the same link, and it syncs like any other field.

• Nest a card under another linked card and its Linear issue becomes a sub-issue of that card’s issue. Take it back out and the issue goes back to the top level.
• Nest or move a sub-issue in Linear and the card moves under its new parent on the map within seconds.
• Send a nested set of cards to Linear and parents are created first, so their children arrive as sub-issues.
• Link an issue whose sub-issues are already on the map and they nest under its card. The same goes for an issue whose own parent is already on the map.

Two cases can’t be mirrored exactly:

• The parent card isn’t linked yet. The Linear issue keeps its current parent. Once you send the parent card to Linear, its linked children nest under the new issue.
• The Linear parent isn’t on this map. A card whose parent came from Linear moves to the top level. A parent that exists only in CardBoard stays, since Linear never knew about it.

Nesting is structure, not position. On tree maps, where a card’s parent decides where it sits, the map re-tidies around the change. Everywhere else, cards stay where you put them.

Coupled fields, decoupled position

Rename an issue in Linear and the card follows. Regroup the whole map around a new release plan and not one Linear issue changes. Why position never syncs.

How the connection maps

• Your CardBoard workspace connects to one Linear workspace.
• Each board connects to exactly one Linear team.
• Each card links to exactly one issue in that team.

The workspace grant

CardBoard connects to Linear as an app, not as a person. One admin authorizes it once for the whole Linear workspace. After that, everyone in your CardBoard workspace works through that single connection, and nobody else has to sign in to Linear from CardBoard.

• One grant per Linear workspace. The authorization belongs to your CardBoard workspace, not to the admin who clicked Approve. If that admin leaves, sync keeps running.
• Boards opt in one at a time. A map syncs only after someone connects it to a Linear team. Teams no map is connected to are never read into CardBoard.
• Scopes requested: read and write. CardBoard does not request admin, and it does not request the agent scopes (app:assignable, app:mentionable), so the app can’t be assigned issues or mentioned like a teammate.
• Access tokens expire every 24 hours. CardBoard refreshes them automatically.

Before you start

• In CardBoard: you need to be an admin or owner of the CardBoard workspace, and the workspace needs a paid plan. See plan limits.
• In Linear: installing an app for the workspace takes a Linear admin. If your workspace requires approval for third-party apps, a member can request CardBoard and an admin approves it from Linear’s settings.

Connect CardBoard to Linear

1. In CardBoard, open Settings → Integrations for your workspace and choose Connect on the Linear card. You can also start from a map’s tracker drawer, which shows Connect workspace to admins.
2. Linear shows its consent screen. Review what CardBoard is asking for and approve it.
3. You land back in CardBoard, which confirms the connected Linear workspace by name.
4. Open a map, open the tracker drawer, and pick the Linear team this map should sync with. Each map connects to one team.

Once a team is connected, its issues appear in the drawer. Drag an issue onto the map to link it to a new card, or send cards you’ve planned to Linear to create issues from them.

What CardBoard reads

From teams that a map is connected to:

• Issues: identifier (like ENG-123), title, description, workflow state, estimate, parent issue, and link.
• Workflow states and estimate settings for each connected team, so CardBoard can map Linear’s states onto card statuses and send only estimates the team’s scale allows.
• Your workspace and team names, so you can pick a team and see which workspace is connected.
• Change events Linear sends through the app’s webhook. CardBoard acts on issue changes and on the app being uninstalled. Issue changes in teams no map is connected to are dropped on arrival.

CardBoard does not read or store Linear comments, projects, cycles, documents, or customer requests.

What CardBoard writes

CardBoard writes to Linear only when someone in your CardBoard workspace links a card to an issue, changes a linked card, or sends a card to Linear.

• Creates issues in the connected team when you send cards to Linear.
• Updates title, description, status, estimate, and parent on linked issues when those change on the card.
• Adds a link back to the card on every linked issue, shown as a “CardBoard Card” attachment. Anyone who opens the issue in Linear is one click from the map. The link is the plain card URL, so it grants no access: people outside your CardBoard workspace have to sign in or be invited.

CardBoard never deletes Linear issues, never changes assignees, and never changes team or workflow settings. Deleting or archiving a card in CardBoard leaves its Linear issue alone.

How edits are attributed

Linear shows who made each change, and CardBoard’s writes appear two ways:

• Issues created from CardBoard show the person who created them, labelled “Name (via CardBoard)”.
• Updates to existing issues show as the CardBoard app. Linear doesn’t let apps attach a person’s name to an update.

CardBoard records the member behind every write in its own audit log, so an admin can always trace an update back to the person who made it.

Who can edit linked cards

Anyone who can see a map sees its linked cards. Editing a linked card takes a CardBoard workspace member on a paid plan, because each edit writes to your Linear workspace. Guests can view, comment on, and react to linked cards, but can’t change them.

Disconnect or uninstall

You can end the connection from either side:

• From CardBoard: a workspace admin opens Settings → Integrations and chooses Disconnect on the Linear card. CardBoard revokes its token with Linear.
• From Linear: a Linear admin removes CardBoard from the workspace’s applications. Linear notifies CardBoard, and CardBoard stops syncing right away.

Either way, CardBoard deletes its access tokens and stops reading and writing. Your cards stay on their maps with their current content, and your Linear issues stay exactly as they are. To pick up where you left off, reconnect from Settings → Integrations.

To change which teams the app can see, a Linear admin can edit CardBoard’s team access on the app’s page in Linear settings.

Data and privacy

Synced issue content (title, description, status, parent, identifier, and link) is stored on the linked cards. See the privacy policy for retention and your rights. For security questions, see security and compliance, or write to support@cardboardit.com.

Planning with Linear

Why position stays on the map, and which story mapping tools connect to Linear: Story mapping for Linear.

Day-to-day

What to link, conflict handling, and migrating off work the same way for every tracker. See Working with your tracker.