Linear Integration

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.

​

What Statisfy Pulls from Linear

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.

​

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. 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 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: 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.

​

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

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.

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.

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.

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.

​

Need Help?

For OAuth issues or complex resolver chains, contact support@statisfy.com.