# Linear

## About Linear integration

Adding the integration will let you simultaneously create, edit, and update items in Timebook and the selected Linear workspace.

The integration allows for two types of synchronization:

1. **One-directional synchronization** – only updates to Timebook items are reflected in Linear, not the other way around. Requires authentication over an API key.
2. **Bidirectional synchronization** – work items are fully synchronized between both Timebook and Linear. Requires authentication over an API key and configuring a webhook.

## Requirements

{% hint style="warning" %}
To add the integration, you must:

* create a dedicated service account in Linear with R/W access to the teams that you want to synchronize
* use the account to configure the API token and webhook
* once configured, log out from the service account and use your regular Linear account for work
  {% endhint %}

{% hint style="info" %}
The account's name will be used as the username in Timebook in notifications for synchronization events.
{% endhint %}

## One-directional synchronization

### Method 1: OAuth

{% stepper %}
{% step %}
Go to **Workplace settings** → **Integrations** and click Lineaar. Select **OAuth** as the access method.
{% endstep %}

{% step %}
Next, select the teams that you want to sync and accept the request in Linear.

{% hint style="warning" %}
Make sure you're logged in to Linear as the dedicated service account.
{% endhint %}

<div align="left"><figure><img src="https://3284049081-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvCMXgzPoiE4UXP4jn6B8%2Fuploads%2FBGbfyxGKOfTm52sN8378%2Flinear-oauth.png?alt=media&#x26;token=edcdcc0b-91b5-4313-b552-b383705a5969" alt="" width="375"><figcaption><p>OAuth access request screen in Linear</p></figcaption></figure></div>
{% endstep %}
{% endstepper %}

### Method 2: Access token

{% stepper %}
{% step %}
Go to **Workplace settings** → **Integrations** and switch to the **Linear** tab. Select **Access token** as the method and click the button to begin configuration.
{% endstep %}

{% step %}
In your Linear account, go to to **Settings** → **Security & Access** and create a new Personal **API key** with the following permissions:

{% hint style="info" %}
**Read**: Read all workspace data available to you\
**Write**: Read and write all workspace data available to you
{% endhint %}

{% hint style="success" %}
You can also restrict access to selected Linear teams.
{% endhint %}

<div align="left"><figure><img src="https://3284049081-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvCMXgzPoiE4UXP4jn6B8%2Fuploads%2Fgit-blob-6f0477ffd911df8ef7d5ff59ba246d06ee2fcacc%2FCleanShot%202025-10-27%20at%2011.44.41%402x.png?alt=media" alt="" width="563"><figcaption><p>API key configuration settings in Linear</p></figcaption></figure></div>
{% endstep %}

{% step %}
Copy the API key and paste it back to Timebook.
{% endstep %}
{% endstepper %}

## Bidirectional synchronization

{% stepper %}
{% step %}
In the Linear settings, go to **Administration** → **API** and configure a webhook with these scopes:

{% hint style="info" %}
**Data change events**: Issues, Projects
{% endhint %}

{% hint style="success" %}
If restricting to specific teams, make sure that they match those selected in the API key.
{% endhint %}
{% endstep %}

{% step %}
Copy the **signing secret** and use it generate the webhook URL in Timebook. Paste it back to Linear to finish the webhook creation.
{% endstep %}
{% endstepper %}

In the end, your Linear settings in Timebook should look like this:

<div align="left"><figure><img src="https://3284049081-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvCMXgzPoiE4UXP4jn6B8%2Fuploads%2FMtmDvTTZOVfw2Xcuwbh9%2Flinear-configured.png?alt=media&#x26;token=c6a4a06b-10e9-417e-81c4-60ddf533f018" alt="" width="375"><figcaption><p>Example of configured Linear integration settings (OAuth)</p></figcaption></figure></div>

## Syncing with Linear team

The last part is selecting the team in Linear that will be synchronized with Timebook. Depending on whether you have Teams activated, you can synchronize Linear in two ways:

1. **Team**: all work items in the selected Timebook team
2. **Project**: all work items in the selected Timebook project

{% hint style="warning" %}
Please mind you must have admin rights to configure synchronization between services.
{% endhint %}

### Project-level synchronization

{% hint style="info" %}
Synchronizing on this level will create a new project in Linear with all work items from the selected Timebook project.
{% endhint %}

{% hint style="success" %}
This method also applies to Timebook solutions.
{% endhint %}

{% stepper %}
{% step %}
Go to the project with the work items you want to sync.
{% endstep %}

{% step %}
Expand project options with `...` , top-right, and click 'Send to Linear'.

<div align="left"><figure><img src="https://3284049081-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvCMXgzPoiE4UXP4jn6B8%2Fuploads%2FQICIV1zPLWwv8SP8gyKs%2FCleanShot%202025-12-15%20at%2010.48.41.png?alt=media&#x26;token=dbf08a86-64fe-4567-a748-b5b7685c0558" alt="" width="563"><figcaption><p>Project settings with Linear synchronization option.</p></figcaption></figure></div>
{% endstep %}

{% step %}
Select the team in Linear and click the button to connect both services.
{% endstep %}
{% endstepper %}

### Team-level synchronization

{% hint style="info" %}
Synchronizing on the team level will send updated work items assigned to your Timebook team to the selected Linear team.
{% endhint %}

{% stepper %}
{% step %}
Go to the settings of the Timebook team you want to sync.
{% endstep %}

{% step %}
Switch to **Work Items** → **Linear integration** and select your Linear team.

<div align="left"><figure><img src="https://3284049081-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvCMXgzPoiE4UXP4jn6B8%2Fuploads%2Fgit-blob-fd2f47be2bd512920b08009549fcf8f3cdfeea3c%2Flinear-4.png?alt=media" alt="" width="563"><figcaption><p>Selecting Linear team to synchronize in Timebook team settings</p></figcaption></figure></div>
{% endstep %}
{% endstepper %}