Linear <> Span Integration

Span's Linear integration reads issues, projects, milestones, initiatives, and users from your Linear workspace with a personal API key, so you can track planning, delivery, and issue cycle time in Span.

Why it matters

Linear is where many teams plan and track work. Connecting it lets Span measure issue cycle time and volume, link issues to pull requests, and show where engineering effort goes, next to your code metrics.

How it works

• Read-only: Span only reads from Linear. It never writes.

• Personal API key: the key belongs to one Linear user and sees exactly what that user can see. OAuth tokens and OAuth app credentials don't work.

• Scheduled sync, no webhooks: Span pulls data about every 2 hours. You don't configure anything on the Linear side.

• One Linear workspace per Span organization.

Span treats every Linear issue as a single "Task" type, because Linear doesn't distinguish stories, bugs, and subtasks the way Jira does.

Metrics and features powered by Linear

• Issue cycle time, with percentile analysis.

• Issue lifetime, from creation to completion.

• Completed and open issue volume.

• Work allocation: investment mix from Linear initiatives, projects, and issue activity, correlated with pull requests and other sources.

Setup

Before you begin, you need the Manage Integrations permission in Span (Owners, Admins, and the Integration Admins group have it by default) and a Linear user with read access to every team Span should analyze. The user only needs read access. A regular user with broad permissions is fine, since Span only reads.

Step 1: Create a Linear personal API key

1. In Linear, go to Settings → Account → Security & Access.

2. Under Personal API keys, click Create key.

3. Give it a label such as Span Integration.

4. Set permissions to Read (or Full access). Span only reads, so extra scopes go unused.

5. Don't limit the key to specific teams unless you want Span to see only those teams. A team-restricted key connects fine but syncs an incomplete dataset.

6. Copy the key. It starts with lin_api_, and Linear shows it only once.

If the Personal API keys section is missing, a workspace admin may have turned off member API keys under Settings → Administration → API. An admin can turn the setting back on, or create the key themselves.

Step 2: Connect Linear to Span

1. In Span, go to Settings → Integrations and click Connect on the Linear card.

2. Paste the personal API key.

3. Continue. Span checks the key against Linear before it saves the connection.

Things to know

• Personal API key, not OAuth. Linear's Settings → Administration → API page is for OAuth apps and workspace key policy. Create the key from your own account under Security & Access.

• The key is tied to one user. It inherits that user's team access and stops working if the user is deactivated. For a long-lived connection, create the key from an account that will stay in the workspace. A dedicated Linear user is optional but recommended.

• Rotating the key keeps your history. Open the Linear integration and choose Edit (or Reconnect), then paste the new key. Span updates the same connection, so past data stays. The new key can come from a different user, but it must belong to the same Linear workspace. A key from another workspace is refused.

• Revoked keys pause sync. Span checks credentials every 6 hours and pauses the connection after two failed checks in a row, with a Reconnect required badge.

• No issue SLA metrics. SLA tracking relies on Jira-specific features.

• No issue subtype metrics. Metrics such as "Done Stories" or "Done Bugs" aren't available, because Linear uses a single issue type.

• Sprint Tracking needs Jira. Span's Sprint Tracking page reads Jira Scrum boards only.

Troubleshooting

Related articles

Supported integrations

Issue Lifecycle Report

How to create an Integrations Admin in Span

Need help?

Contact your Span account team or reach out to support@span.app.