Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pipeshub.com/llms.txt

Use this file to discover all available pages before exploring further.

Linear Logo

​
Linear

Modern issue tracking and project management

✅ Ready📖 Documentation Available

​
Overview

Linear is a modern issue tracking and project management platform designed for high-performance software teams. It provides streamlined workflows, keyboard-first design, and powerful integrations to help teams build products faster.

​
Linear Data Structure

The connector understands Linear’s hierarchical data model:
  • Teams
    • Issues (with comments, attachments, documents, and embedded files)
    • Projects (with milestones, updates, external links, and documents)
  • Users (team members with profiles and emails)

​
What Gets Synced

The connector indexes the following content for AI-powered search:
Content TypeDetails
IssuesTitle, description, status, priority, labels, identifiers (e.g., ENG-123), assignee, creator, type, and parent issue (sub-issues)
CommentsFull comment threads organized by thread ID with author info and timestamps
AttachmentsExternal links attached to issues
DocumentsLinear documents linked to issues and projects
FilesFiles from descriptions/comments (images as base64, others as FileRecord)
ProjectsDescription, content, milestones, updates, comments, external links, and documents
UsersProfiles with IDs, emails, and display names
PermissionsTeam-level access controls (public vs. private teams)

​
Configuration Guide

The Linear connector uses OAuth 2.0 for authentication. Linear’s OAuth apps return refresh tokens that auto-refresh, so a single authorization keeps syncing indefinitely.

​
Step 1: Access Linear API settings

  1. Go to linear.app/settings/api and sign in with your Linear account (must have admin access to your workspace).
  2. You’ll see the API page where you create and manage OAuth 2.0 applications.
Linear API Settings Page
It is recommended to create a dedicated Linear workspace for managing OAuth apps, since any admin on the workspace can see the application credentials.

​
Step 2: Get the Redirect URL from PipesHub

Before creating the OAuth application in Linear, copy the Redirect URL from PipesHub.
  1. In PipesHub, go to Workspace Settings → Connectors, find Linear, and click + Setup for a new instance.
  2. The connector panel opens as a right-side drawer. On the Authenticate Instance tab, copy the Redirect URL.
PipesHub Linear Authenticate Instance tab — copy the Redirect URL

​
Step 3: Create a new OAuth 2.0 application

  1. Back on the Linear API page, find the OAuth Applications section.
  2. Click the + button to create a new application.
  3. Fill in the application details:
    • Application name: a meaningful name (e.g., PipesHub Linear Connector)
    • Developer name: your name or organization name
    • Developer URL: your website URL (e.g., https://your-domain.com)
    • Description: optional description of the application
    • Callback URLs: paste the Redirect URL you copied from PipesHub (Step 2)
Create OAuth 2.0 Application Form
Linear OAuth Application Additional Scopes
  1. Configure the additional settings (leave all toggles OFF):
    • Public — keep OFF; the connector is only for your organization
    • Client credentials — keep OFF; not needed for standard OAuth flow
    • Webhooks — keep OFF; the connector uses scheduled polling
  2. Click Create to create the application.
The Callback URL must match exactly between Linear and PipesHub. Any mismatch — trailing slash, protocol, casing — will cause authentication to fail.
OAuth 2.0 applications created from October 1, 2025 onwards have refresh tokens enabled by default. Access tokens last 24 hours and are automatically refreshed.

​
Step 4: Copy Client ID and Client Secret

After creating the application, you’ll see the application settings page.
  1. Copy the Client ID — used as Client ID in PipesHub.
  2. Click to reveal and copy the Client Secret — used as Client Secret in PipesHub.
OAuth 2.0 Credentials
Store the Client Secret securely. It can be regenerated if needed, but you’ll have to update your PipesHub configuration with the new value and re-authorize.

​
Step 5: Authenticate Instance tab — enter credentials

The connector drawer in PipesHub has three tabs: Authenticate Instance, Authorize, and Configure Records. Return to the Authenticate Instance tab.
  1. Confirm the Redirect URL matches the Callback URL you saved in Linear in Step 3.
  2. If your admin has pre-registered an OAuth app, pick it from the OAuth app dropdown. Otherwise leave it blank and enter credentials manually.
  3. Enter:
    • Client ID — from Step 4
    • Client Secret — from Step 4
  4. Click Next to move to the Authorize tab.
Authenticate Instance tab — enter Client ID and Client Secret

​
Step 6: Authorize tab — complete the OAuth flow

On the Authorize tab, all the OAuth authorization work happens. The tab shows an Authenticate button to kick off the OAuth handshake.
PipesHub Authorize tab with the Authenticate button
  1. Click Authenticate to start the OAuth flow. A popup opens to Linear’s authorization page showing your application name and the workspace it will authenticate with. Permissions requested: Read access to your workspace.
Linear OAuth Consent Screen
Authorize using the same email as your PipesHub account. Using a different email causes permission issues on the PipesHub platform.
  1. Click Authorize to grant access.
  2. The popup closes and returns you to PipesHub. The connector tile shows an Authenticated badge with a Reauthenticate option.
  3. Click Next to move to the Configure Records tab.
The connector requests only read access to your workspace. It does not create, modify, or delete any Linear data.

​
Step 7: Configure Records tab — sync settings, filters, and indexing

On the Configure Records tab, control how the connector syncs and what gets synced. Sync settings — configure your synchronization preferences first:
  1. Sync Strategy — Scheduled or Manual.
  2. Sync Interval — how often to sync (default: 60 minutes).
Configure Sync Strategy
Scheduled sync runs automatically at the specified intervals. Manual sync requires you to trigger synchronization on-demand.
Sync filters — determine which content is downloaded from Linear. Data excluded by sync filters is never downloaded.
Linear Filters Configuration
Available sync filters:
  1. Enable Manual Indexing — control indexing trigger method.
    • Enabled: records are indexed only when you manually trigger it.
    • Disabled (default): records are indexed automatically after sync.
  2. Teams — filter issues and projects by team.
    • Operator: In (include only) or Not In (exclude)
    • Selection: searchable dropdown of all your Linear teams (e.g., “Engineering”, “Design”, “Product”)
    • Leave empty to sync all teams.
The team list is dynamically fetched from your Linear workspace. Type to search and filter; select multiple teams as needed.
  1. Modified Date — filter by last modification date. Operators: Is After, Is Before, Is Between.
  2. Created Date — filter by creation date. Same operators.
Indexing filters — control what synced data gets processed for AI search. All data is synced, but only enabled content types are indexed.
  • Index Issues (default: enabled) — include issue content and comments in search
  • Index Issue Attachments (default: enabled) — include external link attachments in search
  • Index Issue Documents (default: enabled) — include Linear documents in search
  • Index Issue and Comment Files (default: enabled) — include files extracted from issue descriptions and comments
  • Index Projects (default: enabled) — include project content, milestones, and updates in search
Example configurations:
  • Sync only Engineering team: Teams → Operator In → select “Engineering”
  • Exclude archived teams: Teams → Operator Not In → select archived teams
  • Recent issues only: Modified Date → Operator Is After → Date 2024-06-01
  • Index issues but not attachments: disable Index Issue Attachments
  • Index everything except files: disable Index Issue and Comment Files
Click Save to save your configuration. PipesHub confirms the instance is ready with a final dialog — “Instance is configured and ready to sync” — offering two choices: I’ll do it later or Start syncing now.
Instance is configured and ready to sync — I'll do it later or Start syncing now
Choose Start syncing now to kick off the initial sync immediately, or I’ll do it later to enable the connector without an immediate sync. Monitor the Indexing Progress to track sync completion.

​
Supported Features

The Linear connector provides:
  • Full content sync — Teams, issues, projects, comments, attachments, documents, and files
  • Incremental sync — only fetches changes since last sync using updatedAt timestamps
  • Batch processing — fetches data in optimized batches (50 issues, 10 projects per request)
  • Permission preservation — respects team-level public/private access controls
  • Dual group tracking — UserGroups (membership) and RecordGroups (content organization)
  • Fault tolerance — per-team checkpoints enable sync resumption on failures
  • File handling — images embedded as base64, other files synced as separate FileRecords

​
Permission Model

Linear uses a team-based permission model:
Team TypePermission Behavior
Public TeamsAll organization members can view team content
Private TeamsOnly team members can view team content
The connector preserves these permissions:
  • For public teams, content is visible to all organization users in PipesHub.
  • For private teams, content is only visible to team members in PipesHub.

​
Troubleshooting

​
Common Issues

Invalid client credentials error:
  • Verify Client ID and Client Secret are correct
  • Ensure you copied the full values without extra spaces
  • Check that the OAuth app is active in Linear API settings
  • Regenerate the secret if necessary and update PipesHub
Callback URL mismatch error:
  • Ensure the Redirect URI in PipesHub exactly matches the callback URL in Linear
  • Check for trailing slashes or protocol differences (http vs https)
  • Update both configurations to use the same URL
Authorization failed:
  • Verify you’re signing in with an account that has Linear access
  • Ensure you have the necessary permissions in your Linear workspace
  • Check that the OAuth application is properly configured
No data syncing:
  • Verify the connector status shows “Active”
  • Check that the authenticating user has access to Linear teams
  • Ensure teams are not archived or restricted
  • Review sync logs for specific error messages
Permission denied for specific issues:
  • Verify the authenticating user has access to the team containing the issues
  • Check team privacy settings (public vs. private) in Linear
  • Ensure the user is a member of private teams
Missing comments or attachments:
  • Comments are synced as part of issues - ensure “Index Issues” filter is enabled
  • Attachments require “Index Issue Attachments” filter to be enabled
  • Check that the authenticating user has permission to view comments/attachments
  • Ensure the content exists on the issues in Linear
Files not appearing:
  • Only files from Linear’s upload service (uploads.linear.app) are extracted
  • External file URLs from other services are not indexed
  • Check that “Index Issue and Comment Files” filter is enabled
If you modify OAuth application settings in Linear (Client ID, Secret, or callback URL), you must update the configuration in PipesHub and re-authorize the connection.

​
Connector Workflow

The Linear connector follows a structured synchronization process to ensure all data is accurately synced and permissions are properly maintained.

​
Sync Order

The connector syncs data in the following order:
  1. Users → Sync all Linear users with their profiles
  2. Teams → Sync teams with membership and permission settings
  3. Issues → Sync issues with comments and embedded files per team
  4. Attachments → Sync external links attached to issues
  5. Documents → Sync Linear documents linked to issues
  6. Projects → Sync projects with milestones, updates, and related content
  7. Deletions → Detect and remove deleted/archived issues and projects

​
Full Sync vs Incremental Sync

Full Sync occurs when:
  • First-time synchronization
  • Manual full sync is triggered
Incremental Sync occurs when:
  • Previous sync completed successfully
  • Only fetches content modified since last sync
  • Resumes from last checkpoint if interrupted

​
What Gets Processed

Issues: Title, description, comments (organized by threads), status, priority, assignee, labels, and embedded filesProjects: Description, content, milestones, updates, comments, external links, and documentsAttachments & Documents: Synced separately to capture additions even when parent issue wasn’t modifiedDeletions: Automatically detects trashed/archived content and removes from index along with related records

​
FAQ

The initial sync duration depends on several factors:
  • Workspace size: Number of issues, projects, and teams
  • Network latency: Connection speed to Linear’s API
  • Content complexity: Issues with many comments and attachments take longer
The connector fetches data in batches of 50 items per API request for optimal performance. Each team is processed sequentially with per-team checkpoints, allowing sync to resume from the last successful point if interrupted.Tips to speed up initial sync:
  • Use team filters to sync only the teams you need
  • Use date filters to exclude old/archived content
  • Disable indexing filters for content types you don’t need (e.g., attachments, files)
The Linear connector requests the following OAuth scopes:
ScopeDescription
readRead access for your account data (required)
The connector only requires the read scope for team synchronization, providing read-only access to your Linear data. It does not create, modify, or delete any Linear data.
Not currently. The connector uses scheduled polling-based synchronization rather than real-time webhooks. Incremental syncs occur at the configured interval (default: 60 minutes) to capture changes.
Currently, the connector does not support filtering by specific projects. You can filter by:
  • Teams: Sync only specific teams
  • Modified Date: Sync only recently modified content
  • Created Date: Sync only recently created content
Since projects belong to teams, filtering by team will effectively filter the associated projects as well.
There are three common causes:
  1. Email mismatch - The email used during connector authentication doesn’t match your PipesHub account email. This causes permission issues preventing you from accessing synced data.
    • Fix: Reconfigure the connector and authenticate using the same email as your PipesHub account.
  2. Records show in “All Records” but not in search - Documents display in the All Records section but don’t appear in search query results.
    • Fix: Verify sync filters in the connector settings and ensure indexing has completed. Check that the data matches your search query criteria.
  3. Data not yet indexed - The connector is still syncing or hasn’t completed the initial indexing process.
    • Fix: Go to Workspace Settings → Connectors, check the sync status, and wait for indexing to complete.

​
Ready to Get Started?

Connect your Linear workspace to PipesHub in just a few minutes. Follow the step-by-step guide above to enable organization-wide issue tracking search across all your Linear content.