Documentation Get help

Connect Linear

Connect Linear to bring your projects and issue activity into Flowstate, where they become effort, cost, capitalisation and R&D evidence. Flowstate only reads from Linear.

You need access to integrations. Ask your Flowstate admin. For the whole set-up, including linking projects, see Connect your project tool.

Before you start

  • Your people in Flowstate, with the email address they use in Linear. See People and teams.
  • A Linear API key with read access to your workspace.

You can connect one project tool at a time.

Connect Linear

  1. Go to Settings → Integrations, select Browse catalog and open Linear.
  2. Select Connect.
  3. In API URL, enter https://api.linear.app/graphql.
  4. In API Key / Token, paste your Linear API key.
  5. Select Test Connection. When it passes, select Continue.
  6. Choose whether to Auto-create Flowstate projects, then select Continue.
  7. Check the summary and select Complete Setup. The Configure Linear page opens.
  8. On the Data Mapping tab, under Project Source, choose Linear Projects or Issue Type. Do this before the first sync: changing it later means clearing out the projects created the first way.
  9. On the Sync Settings tab, choose how far back to read under Initial Sync History Limit, then turn on Scheduled Sync, choose a Time of Day and select Save Schedule.
  10. Match people and teams. See Match people and teams from your tools.

To come back to these settings, select Configure on the Linear row of Settings → Integrations, then Configure on Linear again.

Check it’s working

Go to Settings → Integrations → Sync Health and open the Linear tab. When the first sync has finished, the status is Healthy and the counts of Projects, Tasks, Users and Activities are above zero. See Check and fix syncing.

What syncs

  • Projects, their issues, who each issue is assigned to, status changes and teams.
  • Once a day at the time you choose. Add a webhook to see changes as they happen.
  • Nothing goes back to Linear.

Optional settings

These are on the Data Mapping tab.

SettingWhat it does
Initiative SyncBrings Linear initiatives in as Flowstate initiatives. Choose Auto-create initiatives or Suggest for review, then select Save Initiative Sync.
Custom Field MappingsUses a Linear field to put a project in a cost centre, department or value stream, or to link it to a Flowstate project by name. Select Add Mapping, enter the field name (such as isCapex) in Source Field, choose a Field Type, then select Save Mappings.
Delivery Status MappingMatches Linear statuses to Flowstate’s delivery statuses. A linked project’s status then comes from Linear.
Effort Tracking ConfigurationChooses which work item types count towards effort, under Task Types to Include. This applies to your whole organisation.

See changes as they happen

  1. In Flowstate, open the Webhooks tab and copy the Webhook Endpoint URL.
  2. In Linear, go to Settings → API → Webhooks and select New webhook.
  3. Paste the URL.
  4. Turn on events for Issues (create, update and remove) and Comments (create).
  5. Select Create webhook.

Replace expired credentials

If the API key expires or is revoked, syncing stops and a red banner says “Linear authentication failed — sync is paused.”

  1. Create a new API key in Linear.
  2. Open Linear’s settings and, on the Connection tab, select Edit Credentials.
  3. Paste the new key into API Key / Token and select Save Changes.

Done when: the banner has gone. To sync straight away, select Sync now on Sync Health.

Start again or disconnect

On the Advanced tab, under Danger Zone:

  • Purge LiveProjects deletes every project created from this connection. Use it only before syncing again with a different Project Source.
  • Delete Integration removes the connection.

Neither can be undone.

If something’s not right

Nothing is showing yet. The first sync reads your history back as far as Initial Sync History Limit, so it takes a while. Sync Health shows Syncing until it’s done.

A project’s status keeps changing back. Its status comes from Linear. Change it in Linear, or adjust Delivery Status Mapping.

Syncing has stopped with an “authentication failed” banner. Replace the API key.

Someone’s work isn’t counted. They aren’t matched to a person, or aren’t in Flowstate yet. See Match people and teams from your tools.