Linear Setup Beta

Connect Linear to let the agent search and read your Linear issues, file new ones, update them, and comment on them -- with approval for every change. Map each Junto company to its Linear customer, and the agent keeps to that customer's issues whenever a conversation is about the company. Tickets can also be linked to Linear issues so the requester is told when the work is done.

Junto supports one Linear workspace per organization.

How Junto Connects

You connect Linear with a personal API key. The agent acts as the key's owner, so create the key from an account that can see the teams you want the agent to work in.

Prerequisites

• A Junto Admin or Owner account
• A Linear account that can see the relevant teams and create personal API keys
• Customers set up in Linear, if you want to scope issues by company
• Customer companies in Junto, imported from your PSA, to map to Linear customers

Step 1: Create a Personal API Key in Linear

1. Sign in to Linear with the account the agent should act as.
2. Go to Settings > Account > Security & access.
3. Create a new personal API key, for example named Junto, and copy its value. Store it securely.

Step 2: Configure in Junto

1. Go to Settings > Integrations > Linear.
2. Click Add configuration.
3. Enter the API key from Step 1. Leave Active on.
4. Click Create configuration. Junto checks the key against Linear before saving, and encrypts it when stored.
5. Click Test connection on the configuration card to confirm the connection.

The configuration card shows the connected Linear workspace and the last four characters of the key.

Step 3: Map Companies to Linear Customers

1. Click Map companies on the configuration card.
2. For each Junto company, select its Linear customer.
3. Click Save mappings.

You can also click Run auto-map to match companies to Linear customers by name, then confirm the suggestions you want.

If no Linear customers are listed, add customers in Linear and reopen the dialog.

How Company Scoping Works

• A conversation about a mapped company -- a ticket chat, or an Explore chat where you name the company -- only sees issues linked to that company's Linear customer. Reading or changing any other issue is refused, and other customers linked to a shared issue are hidden. New issues are linked to the company's customer as a customer request.
• An Explore chat that isn't about a company sees the whole Linear workspace, for example "what's assigned to me?".
• An unmapped company can't use Linear until it is mapped.

What the Agent Can Do

Capability	What Junto can do	Risk level
Search issues	Find issues by text, team, workflow state, assignee, priority, label, project, or recent activity. Open issues only, unless you ask for closed ones	Low
Get issue	Read one issue in full, by identifier (such as ENG-123) or URL: description, state, assignee, labels, project, linked customers, and every comment	Low
List teams	List team keys and each team's workflow states	Low
List users, projects, and labels	Look up the exact names used to assign, filter, or label issues	Low
Create issue	File a new issue in a team, with a description, state, assignee, priority, labels, and project	Medium
Update issue	Change an issue's title, description, workflow state, assignee, priority, labels, or project	Medium
Comment on issue	Add a Markdown comment to an issue, for example to record what was found on a related ticket	Medium

All write actions require technician approval before execution. Read-only tools do not require approval.

Where the Tools Are Available

• Explore chat: every Linear capability.
• Ticket chat: searching, reading, creating, updating, and commenting on the ticket company's issues, and listing teams. Users, projects, and labels can't be listed from ticket chat, because they can name other customers; the agent can still use exact names you give it.
• Linear is not used during automatic ticket triage.

Behavior Notes

• Teams, states, assignees, labels, and projects must match existing names exactly. An unknown value is refused before anything is changed. A label that appears in more than one group can be given as Group/Name.
• Linear limits full-text search to about 30 searches a minute, so the agent uses filters when they're enough.

Example requests:

• "What Linear issues are open for Acme?"
• "Read ENG-412 and summarize where it stands."
• "File a Linear issue in the Platform team for the sync error on this ticket."
• "Move ENG-412 to In Review and assign it to Dana."
• "What's assigned to me in Linear this week?"

Linking Tickets to Issues

When a ticket is waiting on work tracked in Linear, link it to the issue. Several tickets can point at the same issue.

1. Open the ticket and find Linked issues in the ticket details panel.
2. Click Link issue.
3. Paste a Linear issue URL or identifier such as ENG-123, and click Link.

Each linked issue shows its current state. Use the unlink button to remove a link. The agent can also link, unlink, and list a ticket's issues, and can add a comment to an issue already linked to the ticket. Linking and commenting on a linked issue don't require approval, and the agent writes those comments as a summary for developers without the requester's name, contact details, or messages.

When a linked issue is closed, each linked ticket gets an approval card with a drafted update for the requester. Click Approve & Send to post it to the requester as a discussion note in your PSA, or Dismiss to skip it. Junto checks linked Linear issues for changes about every 15 minutes, so the card can take a few minutes to appear. If the issue is reopened before anyone answers the card, the card is withdrawn. See Action Requests for how approval cards work.

Managing the Connection

• Replace the key: Click Edit, enter the new key, and click Update configuration. Leave API key blank to keep the current key.
• Change workspaces: A key from a different Linear workspace clears every company mapping, because customers belong to the previous workspace. Reopen Map companies and map companies again.
• Pause the integration: Click Edit, turn off Active, and save. The configuration and mappings remain saved.
• Disconnect: Click Disconnect and confirm. This removes Junto's saved API key and company mappings. Nothing changes in Linear.

Troubleshooting

• Connection test fails -- Check that the API key hasn't been revoked in Linear, and replace it if needed.
• The agent can't see a team's issues -- The agent acts as the key's owner. Use a key from an account that is a member of that team.
• A company's issues aren't found -- Confirm the company is mapped to the right Linear customer, and that the issues are linked to that customer in Linear.
• "Not mapped" or the company can't use Linear -- Open Map companies and map the company to its Linear customer.
• No Linear customers in the mapping dialog -- Add customers in Linear, then reopen the dialog.
• A label, state, or person was refused -- Names must match Linear exactly. Ask the agent to list teams, labels, users, or projects first, or give a grouped label as Group/Name.
• Searches slow down or are refused -- Linear limits full-text search to about 30 a minute. Wait a moment, or ask with filters such as team, state, or assignee instead of free text.