Skip to main content

Linear

Availability
Available CoreAvailable StandardAvailable PlusAvailable ProAvailable Enterprise FlexAvailable PyAirbyte
Support Level
Marketplace
Connector Version
0.2.18 (last updated 3 days ago)
Sync Success Rate
Medium
Usage Rate
High
Data workers used
0.2 per sync (Learn more)
Definition ID
1c5d8316-ed42-4473-8fbc-2626f03f070c

This page contains the setup guide and reference information for the Linear source connector.

Linear is a project management and issue tracking tool designed for software teams. It provides a streamlined interface for managing issues, sprints, and product roadmaps with a focus on speed and simplicity.

Prerequisites​

  • A Linear account
  • One of the following authentication methods:
    • API Key: A Linear personal API key.
    • OAuth 2.0: A Linear OAuth app with a client ID, client secret, and refresh token. A Linear workspace admin has to authorize the app, because the connector installs it at the workspace level.

Setup guide​

Step 1: Choose an authentication method​

The Linear source connector supports API key and OAuth 2.0 authentication.

API key​

  1. Log in to your Linear account.
  2. Navigate to Settings by clicking your workspace name in the sidebar.
  3. Select Security & access from the settings menu.
  4. Scroll to the Personal API keys section.
  5. Click Create key, give the key a descriptive label (for example, airbyte), and click Create.
  6. Copy the API key and store it securely. Linear only displays the key once.

The API key inherits your user's permissions in the workspace. The connector can only sync data you can see in Linear.

For more information, see the Linear GraphQL API documentation.

OAuth 2.0​

  1. Create a Linear OAuth application.
  2. Add the redirect callback URL for your Airbyte deployment to the app's redirect URLs. Linear rejects authorization requests whose redirect_uri isn't registered on the app.
  3. Copy the app's client ID and client secret.

The connector requests the read and customer:read scopes and authorizes with Linear's actor authorization (actor=app), so the authorization installs the app in the workspace instead of acting as the individual who approved it. Linear treats customer:read as an app-only scope and requires admin permissions to install an app, so a workspace admin has to complete the authorization.

If your Airbyte deployment doesn't provide a browser-based OAuth flow, complete Linear's authorization code flow yourself and 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&actor=app&prompt=consent in a browser and approve the app. Generate a random state value and verify it on the callback to protect against CSRF. The prompt=consent parameter forces Linear to show the consent screen. Linear redirects to your redirect URI with a code parameter.
  2. Exchange the code for tokens by sending 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 refresh_token from the response. The connector uses it to mint access tokens, which Linear expires after 24 hours.

Step 2: Configure the Linear connector in Airbyte​

  1. In the Airbyte UI, navigate to Sources and click + New source.
  2. Select Linear from the list of available sources.
  3. Enter a Source name of your choosing.
  4. For Authentication, choose API Key or OAuth 2.0.
  5. Enter the required credentials for your authentication method.
  6. Optionally, enter a Start Date in ISO 8601 format (for example, 2024-01-01T00:00:00.000Z). Only records updated on or after this date are replicated for streams that support incremental sync. If you leave this field empty, the connector defaults to two years before the time of the first sync.
  7. Optionally, adjust the Number of concurrent workers (default 4, range 1–10). Higher values speed up syncs but increase the risk of hitting Linear's rate limits. Users on API key authentication (2,500 requests/hour) should generally stay at or below the default. Users on OAuth authentication (5,000 requests/hour) may increase this value if they have observed headroom in their rate-limit usage.
  8. Click Set up source and wait for the connection test to complete.

Existing connections that authenticated with a Linear API key continue to use API key authentication after upgrading to connector version 0.2.1 or later. If you upgraded an API key connection to 0.2.0 and it no longer passes connection checks, upgrade to 0.2.1 or later.

Supported sync modes​

The Linear source connector supports the following sync modes:

Streams that support incremental sync use the updatedAt field as the cursor. The Start Date you set when configuring the connector is the lower bound for the first incremental sync. Subsequent syncs use the most recent updatedAt value from the previous sync as the new lower bound.

The following streams are full-refresh only because the Linear GraphQL API doesn't expose a filter argument that the connector can use to request only updated records: project_statuses, issue_relations, customer_statuses, and customer_tiers.

Supported streams​

The Linear source connector supports the following streams. Streams marked as incremental 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.
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.
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.

Starting with connector version 0.2.16, new connections pre-select issues, projects, teams, users, comments, cycles, issue_labels, and workflow_states. Enable the other streams yourself if you need them. Existing connections keep the streams you already selected.

Customer Requests streams​

The customers, customer_needs, customer_statuses, and customer_tiers streams read Linear's Customer Requests data. An admin has to enable Customer Requests in Workspace Settings > Customer requests before your workspace has any of this data to sync, so these streams return no records in workspaces where the feature is off. Customer tiers are also defined in those settings, so the customer_tiers stream stays empty until someone configures tiers. See Linear's Customer Requests documentation for details.

Limitations and troubleshooting​

Rate limiting​

The Linear API uses a leaky bucket algorithm for rate limiting. The connector detects rate-limit errors returned by the API and automatically backs off until the rate-limit window resets. Syncs may slow down during backoff periods but will resume without manual intervention.

Linear enforces three types of rate limits:

  • Request limits: 2,500 requests per user per hour for API key authentication, 5,000 for OAuth app authentication. All requests by the same user share the same quota.
  • Endpoint-specific limits: Certain queries have lower per-endpoint limits. The connector respects the X-RateLimit-Endpoint-Requests-Reset header when these are hit.
  • Complexity limits: Each query's complexity is calculated based on the number of requested fields and pagination depth. The maximum single-query complexity is 10,000 points. The hourly complexity budget is 3,000,000 points for API key authentication and 2,000,000 for OAuth.

Workspace-level OAuth applications receive dynamically increased limits based on the number of paid seats. For more information, see the Linear rate limiting documentation.

Archived records aren't synced​

Linear's GraphQL API hides archived records from paginated responses unless the caller requests them explicitly, and the connector doesn't request them. As a result:

  • Archived issues, projects, cycles, comments, and other archived entities never appear in your synced data. The archivedAt field is present in the schemas but is null for every synced record.
  • When a record you already synced is archived or deleted in Linear, it stops appearing in the API response, and Airbyte doesn't delete rows it already synced, so whatever was written stays in the destination. If you need to detect these records, compare a full refresh of the stream against your destination table.

Data availability​

The connector retrieves only the data its credentials can see. With API key authentication, that's everything the key's owner can see in Linear. With OAuth, it's what the installed app can see in the workspace. If teams, projects, or issues are missing from your synced data, check those permissions in Linear first.

IP allow list​

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

Reference​

This connector uses the Linear GraphQL API. All API requests use 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.

Reference​

Config fields reference

Field
Type
Property name
object
credentials
integer
num_workers
string
start_date

Changelog​

Expand to review
VersionDatePull RequestSubject
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
Was this page helpful?