> ## Documentation Index
> Fetch the complete documentation index at: https://help.statisfy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Linear Integration

> Connect Linear to Statisfy, then use self-serve project rules to match issues to customer accounts and sync them as Statisfy tasks.

The Linear integration pulls issues from your Linear workspace into Statisfy as **tasks** linked to the right customer accounts. After the one-time OAuth connection, you control which projects sync, how issues match to accounts, and how Linear workflow states and fields land in Statisfy — all from **Integrations → Linear → Settings**, without contacting support.

<Note>
  New to Statisfy integrations? [Integration Concepts](/integrations/self_serve_configuration) explains the shared building blocks — previews, sync schedules, job status, and configuration history.
</Note>

## What Statisfy Pulls from Linear

| Data Type           | Description                                                                                                            |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Issues**          | Each synced Linear issue becomes a Statisfy task with its title, description, status, priority, due date, and assignee |
| **Projects**        | Statisfy creates a project (and a matching status template) for every Linear project you select                        |
| **Workflow states** | Linear's per-team workflow states become the task statuses inside each synced project                                  |
| **Task fields**     | Configurable list of Linear fields → Statisfy task custom fields                                                       |
| **Account fields**  | Configurable list of Linear fields → Statisfy account custom fields                                                    |

The configuration is anchored on **Linear projects**, not teams. A Linear team is a broad org unit ("Engineering", "Support"), while a project (for example, "Acme Corp Onboarding") is the unit you actually think in terms of. Issues that have no Linear project assigned are skipped.

## Prerequisites

* **Admin access** to both **Linear** and **Statisfy**
* The Linear projects you want to sync are visible to the account that runs the OAuth connection

## Connect Linear to Statisfy

1. **Log in to Statisfy.**

2. Navigate to **Integrations → Admin Apps → Linear → Connect**.

3. Complete the **OAuth authorization** flow to grant Statisfy read access to your Linear workspace.

4. Once connected, Linear appears as **Connected** on the Integrations page. Click the **Settings** cog to configure.

On the settings page, the **Connection** card has a **Test connection** button — click it any time to confirm Statisfy can reach Linear.

<Note>
  The Linear connection is **workspace-scoped**: one shared authorization covers the whole Statisfy tenant, rather than a per-user connection.
</Note>

## Choose Projects to Sync

The **Projects to sync** card lists the Linear projects Statisfy discovered in your workspace. Pick the ones whose issues should flow into Statisfy — changes here save immediately.

Selecting a project does three things:

* Statisfy creates a matching **project** and **status template** on its side (statuses are built from the workflow states of the Linear teams the project spans).
* The project's issues are included in the scheduled sync.
* The project becomes available for **project rules** and **status mapping** below.

## Project Rules

A project rule tells Statisfy how to handle one Linear project's issues: how to match them to customers, which fields to map, and whether to create tasks. Only **one active rule per project** is allowed; issues from projects without a rule fall back to the [default customer resolution](#default-customer-resolution).

Click **Add rule** to open the rule wizard. It walks through five steps:

1. **Project** — pick the Linear project the rule applies to.
2. **Customer matching** — build the resolver chain (next section).
3. **Field mapping** — map Linear fields to Statisfy task and account custom fields.
4. **Status mapping** — override how the project's workflow states map to Statisfy status groups.
5. **Review** — check the summary and run a preview against real issues before saving.

Each rule also has:

* **Creates task** toggle — when off, matching issues do not create a Statisfy task; the rule only writes the mapped account fields (the same projection mode the [Jira integration](/integrations/jira_integration#projection-mode-creates_task--false) offers).
* **Active** toggle — turn it off to pause a rule without deleting it.

## Customer Matching

Customer matching decides which Statisfy account each Linear issue belongs to. You configure a **chain of resolvers** — Statisfy tries each in order and stops at the first match.

Each resolver pairs a **source field on the Linear issue** with a **Statisfy account field to match against**:

* **Source field** — a dotted path on the Linear issue, for example `project.name`, `labels`, `assignee.email`, or `team.key`. The wizard offers a dropdown of discovered fields; type a path directly to use one not in the list. `labels` yields every label on the issue, and each one is tried in order.
* **Match against** — **Account Name** (fuzzy match with a tunable cutoff), **Account Domain** (exact), **CRM Account ID** (exact), or any account custom field key.
* **Transform** (optional) — reshape the value before matching, for example strip a `customer:` prefix from labels like `customer:acme`.

If you use Linear's native **Customer Requests** feature, the customers attached to an issue are available as source fields too: `needs.customer.name`, `needs.customer.domains`, and `needs.customer.externalIds`. These read the actual customer records Linear links to the issue, which is usually the most reliable signal.

Example chain for a shared triage project:

| Order | Source field             | Match against  | Notes                                                                    |
| ----- | ------------------------ | -------------- | ------------------------------------------------------------------------ |
| 1     | `needs.customer.domains` | Account Domain | Exact match on the linked Linear customer                                |
| 2     | `labels`                 | Account Name   | Fallback: a `customer:acme` label, with a transform stripping the prefix |

For a dedicated per-customer project (for example, "Acme Corp Onboarding"), a single resolver matching `project.name` against **Account Name** is usually enough — effectively "this whole project is one customer."

### Default Customer Resolution

The **Default customer resolution** card holds the resolver chain applied to issues from synced projects that have no active rule of their own. Leave it empty if every synced project has a rule.

<Warning>
  **Issues that match no resolver are skipped.** Statisfy does not create new accounts from Linear issues. If many issues have no obvious customer link, add a broader fallback resolver or accept that those issues will be skipped.
</Warning>

## Field Mapping

Field mappings control which Linear fields are copied to Statisfy beyond the standard task fields, and where:

* **Task field mappings** — copied to the Statisfy task created from the issue
* **Account field mappings** — copied to the Statisfy account the issue resolves to

For each entry, pick the **Linear field** (a dotted path such as `priorityLabel`, `state.name`, or `labels`) and the **Statisfy custom field key** it writes to. The Statisfy custom field must already exist in **Object Manager** with a compatible type — the wizard maps onto existing fields, it does not create them.

You can set the mappings at the tenant level (applied to every project) and override them per rule.

## Status Mapping

Statisfy groups every Linear workflow state into one of four task-status groups: **Not started**, **Active**, **Done**, or **Archived**. By default the group is derived from Linear's own state type (backlog and unstarted states map to Not started, started states to Active, completed to Done, and so on).

The **Status mapping** card lets you override the group for any state. Because Linear states are owned by teams, the same state name can exist on several of your selected projects — the editor collapses those into a single row, and your choice applies to every project that shares the state name. Changes here save immediately.

Statisfy commonly maps canceled or duplicate states to **Archived** so they stay out of the Done bucket. You can also set per-project overrides in the rule wizard's status mapping step.

## Preview Before You Rely On It

The **Sample & test** panel at the bottom of the settings page runs your current configuration against a sample of real Linear issues and shows, for each issue, which account it resolved to and via which resolver, plus the overall match rate. The rule wizard's Review step offers the same preview scoped to that rule's project.

If you change the configuration after running a preview, the panel flags the results as stale — re-run it to refresh.

## Security

* The OAuth connection uses Linear's read-only `read` scope — Statisfy cannot modify issues, projects, or workflow states.
* Tokens are stored encrypted and refreshed automatically.
* Statisfy only sees projects the authorizing account can access in Linear.

## Troubleshooting

<Accordion title="No issues are syncing">
  * Confirm at least one project is selected in **Projects to sync**.
  * Confirm the issues are assigned to a Linear **project** — issues without a project are skipped.
  * Use **Test connection** on the Connection card; reconnect from the Linear card under **Integrations → Admin Apps** if it fails.
</Accordion>

<Accordion title="Issues sync but don't link to accounts">
  * Run the **Sample & test** preview — it shows the resolver result per issue.
  * Check that the source field your resolvers point at is actually populated on the issues.
  * Add a fallback resolver (for example, matching a `customer:` label against the account name).
  * For custom field targets, confirm the value on the issue matches a value stored on the account.
</Accordion>

<Accordion title="A task shows the wrong status">
  * Check the **Status mapping** card — the state may need an override (for example, mapping a "Duplicate" state to **Archived** instead of **Done**).
  * Remember that overrides apply per state name across every selected project that shares it.
</Accordion>

<Accordion title="A Linear field isn't showing up in Statisfy">
  * Confirm the field is in the rule's (or tenant's) **Field mapping**, on the right side (task vs. account).
  * Confirm the Statisfy custom field exists in **Object Manager** with a compatible type.
</Accordion>

## Need Help?

For OAuth issues or complex resolver chains, contact [support@statisfy.com](mailto:support@statisfy.com).