Advanced Analytica Advanced Analytica: IBOM
← All connectors
Linear logo

Source connector

Linear

Set up Linear as a source and move its data into your chosen destination.

Version 1.0.3 certified generally available

Linear

Use this page to set up the Linear source connector and find reference information.

Linear helps software teams manage projects and track issues. Its streamlined interface supports issues, sprints and product roadmaps, focusing on speed and simplicity.

Prerequisites

  • A Linear account
  • One of these authentication methods:
    • OAuth 2.0 (Airbyte Cloud): A Linear workspace administrator account permitted to authorise the required workspace data. Airbyte supplies the OAuth application.
    • OAuth 2.0 (Self-managed): A Linear OAuth application, client ID and client secret. You also need a Linear workspace administrator account permitted to authorise the required workspace data. The connector installs the app at workspace level.
    • API Key: A Linear personal API key.
  • To sync the customers, customer_needs, customer_statuses and customer_tiers streams, enable Linear’s Customer Requests feature in your workspace. OAuth connections also need the customer:read scope. API keys don’t use scopes. See Customer Requests streams.

Setup guide

Set up Linear

The Linear source connector supports OAuth 2.0 and API key authentication. From connector version 0.2.19, the setup form selects OAuth 2.0 by default.

OAuth 2.0

  1. Airbyte supplies the OAuth application for Airbyte Cloud. For a self-managed deployment, create a Linear OAuth application.
  2. For a self-managed deployment, add the displayed Airbyte OAuth callback URL to the application’s redirect URLs. Linear rejects authorisation requests when the app doesn’t register the redirect_uri. Copy the application’s client ID and client secret.
  3. In Airbyte, choose OAuth 2.0. For self-managed deployments, enter your Linear application’s client ID and client secret. Then complete the authorisation flow.
  4. Linear access tokens last 24 hours, and the connector refreshes them automatically. Each refresh returns a new refresh token, which the connector stores in the source configuration. Linear rotates the refresh token after every exchange. The previous token then stops working, except during a short replay window for retrying interrupted refreshes.

The connector requests the read, customer:read and initiative:read scopes. It authorises through Linear’s actor authorization (actor=app), installing the app in the workspace. It doesn’t act as the person who approved it. Linear treats customer:read as an app-only scope and requires administrator permission to install an app. A workspace administrator must therefore complete the authorisation.

If your Airbyte deployment doesn’t provide browser-based OAuth, complete Linear’s authorization code flow yourself. Then use the resulting refresh token:

  1. Open https://linear.app/oauth/authorize?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&response_type=code&state=<STATE>&scope=read,customer:read,initiative:read&actor=app&prompt=consent in a browser and approve the app. Generate a random state value and verify it on the callback to prevent CSRF. The prompt=consent parameter makes Linear display the consent screen. Linear redirects to your redirect URI with a code parameter.
  2. Exchange the code for tokens. Send a form-encoded POST request to https://api.linear.app/oauth/token with code, redirect_uri, client_id, client_secret and grant_type=authorization_code.
  3. Copy the response’s refresh_token into the connector configuration. The connector uses it to create access tokens, which expire after 24 hours. The first refresh replaces this token. Don’t reuse it in another source or save a copy for later.

API key

  1. Sign in to your Linear account.
  2. Select your workspace name in the sidebar to open Settings.
  3. Select Security & access from the settings menu.
  4. Go to the Personal API keys section.
  5. Click Create key and give the key a descriptive label, such as airbyte. Then click Create.
  6. Copy and securely store the API key. Linear displays it only once.

The API key inherits your workspace permissions. The connector can only sync data you can view in Linear.

For more information, see the Linear GraphQL API documentation.

Set up the connector in Airbyte

  1. In the Airbyte UI, go to Sources and click + New source.
  2. Select Linear from the available sources.
  3. Enter your chosen Source name.
  4. For Authentication, choose OAuth 2.0, the default, or API Key.
  5. Enter the credentials required for your authentication method.
  6. Optionally, enter a Start Date in ISO 8601 format, such as 2024-01-01T00:00:00.000Z. Supporting incremental streams replicate only records updated on or after this date. Leave this field empty to default to two years before the first sync.
  7. Optionally, adjust the Number of concurrent workers. The default is 4, with a range of 1–10. Higher values accelerate syncs but increase the risk of reaching Linear’s rate limits. OAuth allows 5,000 requests hourly, compared with 2,500 for API keys. However, its hourly complexity budget is lower: 2,000,000 instead of 3,000,000. This connector uses GraphQL, so complexity is usually the binding limit. Increase this value only after confirming available headroom.
  8. Click Set up source and wait for the connection test to finish.

Existing Linear API key connections continue using API key authentication after upgrading to connector version 0.2.1 or later. If an API key connection upgraded to 0.2.0 stops passing connection checks, upgrade to 0.2.1 or later.

Supported sync modes

The Linear source connector supports these sync modes:

Incremental streams use the updatedAt field as their cursor. Your configured Start Date sets the lower bound for the first incremental sync. Later syncs use the previous sync’s latest updatedAt value as the new lower bound.

The lower bound is inclusive. Records matching the stored updatedAt exactly are read again during the next sync. The overlap increases after a failed sync. Each stream has its own cursor, which advances only when that stream finishes. After interruption, a stream rereads everything updated since its last successful run. Streams completed before the failure keep their new cursor and remain unaffected. In Incremental - Append + Deduped mode, the destination collapses repeated records. In Incremental - Append mode, they become extra rows. Deduplicate downstream by primary key if needed.

Some streams only support full refresh because Linear’s GraphQL API provides no filter for requesting updated records alone. These are project_statuses, issue_relations, customer_statuses, customer_tiers and initiative_to_projects. issue_history only supports full refresh for another reason. Linear exposes history through each issue, so the connector reads issues individually. See Issue history.

Supported streams

The Linear source connector supports the following streams. Incremental streams use updatedAt as the cursor field.

StreamIncrementalDescription
attachmentsYesFile and link attachments on issues.
commentsYesComments posted on issues.
customer_needsYesCustomer needs associated with issues.
customersYesCustomer records tracked in Linear’s customer requests feature.
customer_statusesNoStatus definitions for customer records.
customer_tiersNoTier definitions for customer records.
cyclesYesCycles (sprints) for each team.
initiativesYesStrategic initiatives tracked across projects.
initiative_to_projectsNoRelationships between initiatives and projects.
issue_historyNoChanges made to issues over time.
issue_labelsYesLabels that can be applied to issues.
issue_relationsNoRelationships between issues (for example, blocks and duplicates).
issuesYesIssues in every team.
project_milestonesYesMilestones defined inside projects.
project_statusesNoStatus definitions for projects.
project_updatesYesUpdates posted for projects.
projectsYesProjects across all teams.
teamsYesTeams in your Linear workspace.
usersYesUsers in your Linear workspace.
workflow_statesYesWorkflow states (for example, Todo, In Progress, Done) defined by each team.

From connector version 0.2.16, new connections preselect issues, projects, teams, users, comments, cycles, issue_labels and workflow_states. Enable any other streams you need. Existing connections keep their selected streams.

Customer Requests streams

The customers, customer_needs, customer_statuses and customer_tiers streams read Linear’s Customer Requests data. An administrator must enable Customer Requests in Workspace Settings > Customer requests before your workspace has data to sync. OAuth connections also need the customer:read scope. Those settings also define customer tiers. The customer_tiers stream remains empty until someone configures tiers.

:::caution Behaviour change in 0.2.23 Before 0.2.23, the connector reported refused Customer Requests queries as successful, with zero records. From 0.2.23, the sync fails and includes Linear’s reason for refusing the query. If Customer Requests isn’t enabled, deselect customers, customer_needs, customer_statuses and customer_tiers in the connection’s schema tab. See Syncs fail on errors Linear returns in the response body. :::

See Linear’s Customer Requests documentation for details.

Initiative streams

The initiatives and initiative_to_projects streams require Linear’s initiative:read scope. Connector version 0.4.0 requests it. However, Linear grants scopes during authorisation, so OAuth sources created before 0.4.0 have tokens without it. If either stream fails with Invalid scope: initiative:read ... required for app user to read initiative data, a workspace administrator must re-authenticate it under Sources > your source > Settings. API key sources aren’t affected.

Issue history

issue_history is the only stream read through a parent stream. Each sync pages through every issue. It then queries each issue separately for its history, retrieving 50 entries per page. This has two consequences:

  • Request volume and sync time depend on your issue count, not changes since the previous sync. These queries share the hourly request and complexity budgets used by every other stream. In workspaces with many issues, this stream can slow all other streams in the connection. See Rate limiting.
  • The stream has no cursor, so every sync returns the complete history. Use Full Refresh - Overwrite mode unless you need repeated records. In Full Refresh - Append mode, every sync appends another complete copy.

The connector reads parent issues directly. You don’t need to select issues to sync issue_history. Each history record includes an issueId field added from the parent issue. Linear’s response doesn’t include this field. Together, issueId and id form the primary key.

Archived records

Linear hides archived records from API responses by default instead of deleting them. It automatically archives completed issues, cycles and projects over time. Deletion is separate, as described in Limitations & Troubleshooting below. From connector version 0.3.0, every stream requests archived records. They sync alongside active records. Each record’s archivedAt field contains its archive time and is null while active.

Before 0.3.0, the connector didn’t request archived records. Linear omitted them from every response, and archivedAt was always null. Upgrading changes your sync results:

  • Full-refresh streams return all archived records during the next sync. Established workspaces may see a large, one-off volume increase.
  • Incremental streams return archived records only when their updatedAt value is later than the stream’s cursor. Records archived from now on qualify. Records archived before upgrading usually don’t because their updatedAt predates the cursor. To retrieve them, refresh the stream.

Date and timestamp columns

From connector version 1.0.0, the connector declares date and date-time formats for Linear’s temporal fields. Destinations therefore create date and timestamp columns instead of strings. issues.dueDate, projects.startDate, projects.targetDate, project_milestones.targetDate, initiatives.targetDate, issue_history.fromDueDate and issue_history.toDueDate become date columns. Linear stores them as calendar dates without times. Every other temporal field becomes a timestamp column, including createdAt, updatedAt and archivedAt.

This changes existing destination column types. After upgrading, refresh the source schema and clear the affected streams. Update downstream models that cast these columns from strings. See the Linear migration guide.

Deprecated Linear fields

Version 1.0.0 stops requesting these deprecated Linear fields: users.inviteHash, users.calendarHash, teams.inviteHash, teams.private, teams.markedAsDuplicateWorkflowState, its derived teams.markedAsDuplicateWorkflowStateId, and customer_statuses.type. After upgrading, those columns stop receiving values.

The teams stream provides visibility instead of private. It’s a string, not a boolean, with three possible values. public identifies teams visible to every workspace member. private identifies teams visible only to their members. restricted identifies a non-private team within a private team’s boundary. A restricted team isn’t private. Write downstream logic as visibility = 'private' instead of treating every value except public as private.

Limitations and troubleshooting

Rate limits

The Linear API applies rate limits through a leaky bucket algorithm. From connector version 0.2.22, the connector paces requests below your authentication method’s hourly request limit. It distributes requests across the hour instead of sending bursts. The connector also detects API rate-limit errors and automatically waits until the rate-limit window resets. This reactive delay remains important because other applications may consume quota through the same credentials. The connector can’t see that usage or track query complexity. Syncs may slow during pacing or backoff periods, but they resume without manual intervention.

Linear applies three types of rate limit:

  • Request limits: API key authentication allows 2,500 requests per user each hour. OAuth app authentication allows 5,000. All requests from the same user share this quota.
  • Endpoint-specific limits: Some queries have lower per-endpoint limits. When reached, the connector follows the X-RateLimit-Endpoint-Requests-Reset header.
  • Complexity limits: Query complexity depends on the requested field count and pagination depth. A single query can use at most 10,000 points. The hourly budget is 3,000,000 points for API keys and 2,000,000 for OAuth. This connector uses GraphQL, so complexity usually becomes binding before request count.

Workspace-level OAuth applications receive dynamically higher limits based on paid seat numbers. For more information, see the Linear rate limiting documentation.

OAuth authorisation fails

If an OAuth source starts returning an authorisation error, re-authenticate it from its settings page. This issues a new refresh token. Linear rotates the refresh token whenever the connector exchanges it. A source permanently breaks if an older value replaces its stored token. Don’t restore an earlier source configuration or use the same refresh token for multiple sources.

Connector versions before 1.0.1 contained a bug preventing Airbyte Cloud from storing rotated refresh tokens. The connector added an empty api_key field to OAuth configurations. Airbyte Cloud rejects configuration updates containing an empty secret. An OAuth source therefore worked until its first token refresh. Every later sync then failed with Linear’s Refresh token revoked error. If this happens, upgrade to 1.0.1 or later and re-authenticate once. You don’t need any other changes. API key sources weren’t affected.

Connection tests only read issues

The connection test queries the issues stream. It confirms Linear accepts your credentials but doesn’t test other streams. Credentials without access to Customer Requests data still pass. The problem appears only when a sync reads those streams.

Data availability

The connector retrieves only data visible to its credentials. With API key authentication, that’s everything visible to the key’s owner in Linear. With OAuth, it’s everything visible to the installed workspace app. If synced teams, projects or issues are missing, first check their Linear permissions.

Deleted records remain in your destination

When you delete a Linear issue or project, it stays in the team’s Recently deleted tab for 30 days. Linear then permanently removes it. The issues, projects, initiatives and issue_history streams include a trashed field for this state. You can use it to filter these records downstream. No other stream exposes trashed.

After Linear permanently removes a record, the API no longer reports it. Airbyte doesn’t delete previously written rows, so the destination retains it. To find rows missing from Linear, compare a full stream refresh with your destination table.

Response-body errors fail syncs

Linear’s GraphQL API often reports problems in the response body instead of the HTTP status code. From version 0.2.23, a sync fails when this response contains errors and no usable data. Responses the connector retries are excluded. Before 0.2.23, the connector discarded these errors and treated the response as an empty, successful stream. A previously successful connection may therefore start failing after upgrading, even when nothing changed in Linear.

Each failure includes Linear’s explanation. Use that text to choose your next step:

  • Rejected credentials: Check that your API key still exists under Settings > Security & access > Personal API keys in Linear. Alternatively, re-authenticate an OAuth source to issue a new refresh token.
  • Denied access to data or to a feature your workspace doesn’t have: Give the credentials access to that Linear data, or deselect the stream. Customer Requests streams are the most common cause. See Customer Requests streams.
  • An invalid query: This indicates a connector defect, not a configuration problem. Report it to Airbyte support.

Responses containing errors and usable records still sync. If Linear returns partial results, the connector keeps the received records.

The connector retries request timeouts and Linear’s 5xx responses. They fail a sync only when they persist. Rejected credentials, denied access and invalid queries fail immediately, regardless of their status code.

Programmatic configuration

This connector uses the Linear GraphQL API. Every API request uses the https://api.linear.app/graphql endpoint.

For programmatic configuration, use these parameter names:

FieldRequiredDescription
credentials.auth_typeYesAuthentication method. Valid values are API Key and OAuth2.0.
credentials.api_keyRequired for API key authenticationLinear personal API key.
credentials.client_idRequired for OAuth 2.0 authenticationClient ID of your Linear OAuth app.
credentials.client_secretRequired for OAuth 2.0 authenticationClient secret of your Linear OAuth app.
credentials.refresh_tokenRequired for OAuth 2.0 authenticationRefresh token returned by the Linear OAuth flow.
start_dateNoUTC date and time in ISO 8601 format. Records updated before this date aren’t replicated for streams that support incremental sync. If unset, defaults to two years before the first sync.
num_workersNoNumber of worker threads used to read streams in parallel (default 4, range 1–10). Higher values speed up syncs but increase the risk of hitting rate limits.

IP allow list

If you use Airbyte Cloud and restrict access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.

Changelog

Expand to review
VersionDatePull RequestSubject
1.0.32026-09-1585560Update dependencies
1.0.22026-09-1085793Promote to certified support level
1.0.12026-09-0985789Fix bug in config migration that prevented rotated refresh tokens from being persisted
1.0.02026-08-2885095Breaking: declare date and date-time formats on every temporal field, and drop the fields Linear deprecated in the users, teams, and customer_statuses queries (teams.visibility replaces teams.private). See the migration guide.
0.4.02026-08-2785056Add initiatives, initiative-to-project relationships, project updates, and issue history streams
0.3.12026-08-2685053Add regression tests covering incremental cursor boundary behavior
0.3.02026-08-2684950Sync archived records in every stream and declare archivedAt (plus trashed on issues and projects) in the stream schemas
0.2.232026-08-2584949Classify Linear GraphQL errors: surface actionable config errors for invalid credentials, fail fast on invalid queries, and fail any response carrying a GraphQL errors array instead of reporting it as a successful empty stream
0.2.222026-08-2584954Add proactive rate-limit pacing for Linear API requests
0.2.212026-08-2484947Fix OAuth consent scope encoding and persist the access token issued during authorization.
0.2.202026-08-2484947Persist rotated OAuth refresh tokens so OAuth connections keep working after the first token refresh.
0.2.192026-08-2484947Make OAuth 2.0 the default authentication method in the connector setup form
0.2.182026-08-2184948Clarify authentication field titles and descriptions in the connector setup form.
0.2.172026-08-2184951Enable acceptance test suites with GSM test secrets for API key and OAuth
0.2.162026-08-2184944Add suggested streams so new connections pre-select core streams and exclude Customer Requests streams
0.2.152026-08-2184946Update base image and declare a heartbeat timeout
0.2.142026-08-1884676Update dependencies
0.2.132026-08-1184025Update dependencies
0.2.122026-08-0483528Update dependencies
0.2.112026-07-2882981Update dependencies
0.2.102026-07-2182509Update dependencies
0.2.92026-07-1481930Update dependencies
0.2.82026-06-3081147Update dependencies
0.2.72026-06-2380554Update dependencies
0.2.62026-06-1679947Update dependencies
0.2.52026-06-1078237fix(source-linear): Handle GraphQL rate-limit errors
0.2.42026-06-0979388Update dependencies
0.2.32026-06-0278816Update dependencies
0.2.22026-05-1878160Promote release candidate to GA
0.2.12026-05-1278013Fix API key config migration for existing connections
0.2.02026-05-1177578Add OAuth 2.0 authentication
0.1.22026-04-2877318Update dependencies
0.1.12026-04-2176654Update dependencies
0.1.02026-04-1776429Add incremental sync support for 12 streams using the updatedAt cursor field
0.0.362026-03-3175720Update dependencies
0.0.352026-03-1775023Update dependencies
0.0.342026-03-0374239Update dependencies
0.0.332026-02-1073035Update dependencies
0.0.322026-02-0372748Update dependencies
0.0.312026-01-2172240fix(linear): icon
0.0.302026-01-2072027Update dependencies
0.0.292026-01-1471489Update dependencies
0.0.282025-12-1870775Update dependencies
0.0.272025-11-2570007Update dependencies
0.0.262025-11-1869442Update dependencies
0.0.252025-10-2968966Update dependencies
0.0.242025-10-2168296Update dependencies
0.0.232025-10-1468027Update dependencies
0.0.222025-10-0767519Update dependencies
0.0.212025-09-3066807Update dependencies
0.0.202025-09-2466655Update dependencies
0.0.192025-09-0965897Update dependencies
0.0.182025-08-2365391Update dependencies
0.0.172025-08-0964629Update dependencies
0.0.162025-08-0264275Update dependencies
0.0.152025-07-2663892Update dependencies
0.0.142025-07-1963518Update dependencies
0.0.132025-07-1263095Update dependencies
0.0.122025-07-0562601Update dependencies
0.0.112025-06-2862178Update dependencies
0.0.102025-06-2661417Update connector configuration
0.0.92025-06-2161843Update dependencies
0.0.82025-06-1461117Update dependencies
0.0.72025-05-2460728Update dependencies
0.0.62025-05-1059893Update dependencies
0.0.52025-05-0359299Update dependencies
0.0.42025-04-2658781Update dependencies
0.0.32025-04-1958215Update dependencies
0.0.22025-04-1257669Update dependencies
0.0.12025-04-1157586Initial release by @natikgadzhi
Advanced Analytica

Most businesses are sitting on information they can’t use at speed. The people who hold it are busy, and when they leave, the knowledge goes with them. The documents are static, and the processes around them weren’t designed for AI.

Advanced Analytica works with these businesses to turn that information into structured data assets. Once they're integrated, AI systems can govern it, and the business can use it. We bring in the strategy, the specification and the AI skills to rework how the business operates.

MOVE FAST. STAY SAFE.