Skip to main content

Linear

Connect a Linear workspace to ingest its issues, projects, cycles and related data into your organization as datasets you can query alongside the rest of your data. Ingestion only reads from Linear. It never creates or changes anything there.

Connect your Linear workspace​

  1. From your organization, open Integrations in the sidebar. Find Linear (in the Dev category) and click Connect.
  2. Create a personal API key in Linear: create a Linear API key. Paste it into the dialog and click Connect with API key. Read access is enough to ingest data. The key is validated with a read-only request, stored in a secret manager, and never shown again.

Connecting with OAuth is planned. Until then, use a personal API key.

You can connect more than one Linear workspace. To add another, click Manage on the Linear row and then Add workspace. Connecting the same workspace again replaces its stored credential.

Adding a workspace also sets up its first ingestion, which can't be saved while the key reads no team. Fix the key's access in Linear, then click Refresh in that step to check the key again.

Create an ingestion​

Each connected workspace ingests through a single dataset.

  1. On the Integrations page, click Manage on the Linear row and click Add ingestion next to the workspace.

  2. Set the Dataset name. A valid name is suggested from your workspace name; use lowercase letters, numbers and underscores, starting with a letter.

  3. Under Teams, choose what to ingest:

    • All teams — every team the credential can read, including teams created later. The dialog lists the teams it can read now, and you can't add the ingestion while no team is readable.
    • Selected teams — tick the teams you want. Select at least one.

    If the list is empty, or the dialog says This Linear workspace needs reconnecting, fix the key's access in Linear (or have an admin update this workspace's key under Configure), then click Refresh in the dialog to check again without reopening it. A rejected key only affects its own workspace; other workspaces' teams still load.

  4. Click Add ingestion.

The dataset is created and starts syncing right away. To change the teams later, click the pencil icon on the ingestion's row in the Manage dialog.

What the tables look like​

The dataset has one table per Linear entity: organization, users, teams, team_memberships, workflow_states, issue_labels, projects, project_milestones, project_updates, cycles, initiatives, issues, comments, attachments, documents and issue_relations. Each table has an id primary key, and column names are in snake case.

How data is refreshed​

Each run reads only what changed since the last run, using Linear's updatedAt, and includes archived items. Rows are merged on id, with the newest version winning, so re-running is always safe.

If Linear rejects the connection during a run, the run fails and asks you to reconnect. Use Add workspace in the Manage dialog to connect the workspace again.

Remove an ingestion or disconnect a workspace​

  • Delete an ingestion. Click the trash icon on the ingestion's row. This deletes the dataset and stops future syncs. The workspace stays connected.
  • Disconnect a workspace. Click the disconnect icon on the workspace's row. This removes the connection and deletes the workspace's Linear ingestion datasets along with the data already ingested.

Neither action changes anything in Linear. To stop OSO's access completely, also revoke the personal API key in your Linear settings.