# Linear

<figure><img src="/files/s0HrTBWyEJew4jW4M8SB" alt=""><figcaption></figcaption></figure>

### What you get

* **One-click escalation from any request.** Click **Escalate ticket** in the request side panel, pick a Linear team and project, and a linked issue is created with the Siit context pre-filled.
* **Bi-directional status sync.** Status changes on the Linear issue update the Siit request's external status field automatically — and the link stays visible on both sides.
* **IT Agent native support.** `/linear create ticket` is available inside IT Agent playbooks, with optional approval.
* **Workflow-driven issue creation.** Use **Create Linear issue** as a workflow step, with approval gating where needed.
* **Audit trail.** Every Linear action triggered from Siit is recorded on the request timeline.

### How it works

When a Siit request needs engineering or product work tracked in Linear:

1. From the request side panel, click **Escalate ticket** and pick **Linear**.
2. Choose the team, project (optional), labels, and priority. Fill in the title and description.
3. Submit. Siit creates the Linear issue, links it back to the Siit request, and posts the link on both sides.
4. As the Linear issue progresses, status updates flow back to Siit. Use these as workflow conditions — for example, "when the linked Linear issue is Done, set the Siit request to Resolved."

The same flow is available in workflows (as a **Create Linear issue** action).

### What syncs from Linear

* **Issues created from Siit** — every escalated ticket is tracked with its Linear identifier, team, project, and current status.
* **Status changes** — Linear status transitions update the Siit request's external ticket status.
* **Links** — bidirectional links between the Siit request and the Linear issue, visible on both sides.

### Custom field mapping

> **Coming soon.** Custom field mapping for Linear is on our roadmap. For now, you can set the title, description, team, project, labels, and priority when escalating to Linear. To track which fields are exposed, reach out via the in-app chat.

### Before you connect

* A Linear admin (Workspace Admin) to authorize the connection.
* A clear idea of which Linear team(s) you want to escalate to. Start with one, then expand.
* Optional: a dedicated "Siit Integration" Linear user, so the integration survives admin turnover.

### Connect Linear

1. In Siit, go to **Settings → Integrations**, find **Linear** in the Ticketing section, and click **Connect**.
2. Sign in to your Linear workspace as an admin and approve the requested scopes.
3. Pick the Linear team(s) you want available for escalation.
4. Configure the default team, project, and priority for escalations.
5. Test by escalating a sample request from Siit to Linear.

Need a more detailed walkthrough? Reach out to support via the in-app chat.

### After the connection

* **Try the side panel.** From any request, click **Escalate ticket → Linear** and create a test issue.
* **Set up status sync rules.** In **Settings → Integrations → Linear**, map Linear statuses to Siit's external ticket statuses (e.g., Linear "Done" → Siit "Resolved").
* **Build your first workflow.** A common starter: "when service = 'New integration', auto-create a Linear issue in the platform team's backlog and notify the requester."

### Common workflows

**New integration request.** *Trigger: Service = "New integration request". Actions: Manager approval → Create Linear issue in the platform team → DM requester with the Linear link.*

**Bug report auto-escalation.** *Trigger: Service = "App bug report". Actions: Create Linear issue in the engineering team → Set Siit status to Waiting → Notify requester.*

**Auto-resolve on Linear completion.** *Trigger: Linked Linear issue status = Done. Actions: Set Siit request to Resolved → Notify requester.*

### IT Agent integration

Inside an IT Agent playbook, use `/linear create ticket` to let the agent escalate autonomously — with approval gating on the action when you want a human in the loop.

A common playbook: an employee reports a complex issue in Slack → IT Agent gathers context → requests manager approval → creates a Linear issue → posts the link back to the employee.

See IT Agent for playbook examples.

### Tips

* **Use a dedicated service account** for the Linear connection so it survives individual admin turnover.
* **Start with one team.** It's tempting to connect every Linear team — but mapping statuses for one well-used team first is faster and lower-risk.
* **Keep Siit as the employee surface.** Employees shouldn't need a Linear account to track their request. The Siit request stays their canonical view; the linked Linear issue is internal.
* **Use status sync to close the loop.** Mapping Linear "Done" to Siit "Resolved" keeps requesters informed without anyone manually updating the Siit ticket.

### Troubleshooting

**"Authorization failed" on connect.** The admin signing in lacks Linear Workspace Admin rights. Try with a Workspace Admin.

**Team missing from the destination picker.** The Siit Linear user lacks access to that team. Update team membership in Linear and re-sync.

**Status sync isn't updating Siit.** Check the status mapping in **Settings → Integrations → Linear → Status sync**. If a Linear status isn't mapped, transitions through it won't update Siit.

**"Issue created" but no link in Siit.** The Linear issue was created but the back-link save failed. Open the request timeline — the Linear issue ID is logged. Manually re-link if needed, then check Siit's connection token validity.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.siit.io/integrations/ticketing/linear.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.