---
url: https://salimhamed.github.io/jigs/guide/hub-linear.md
---
# Linear app

Factories act on Linear as a Linear OAuth app your [hub](/guide/hub) holds, so
their messages and mentions reach people like anyone else's. People can
mention the app on an issue or delegate an issue to it, as they would a
teammate. The hub receives the app's webhooks, holds each workspace's tokens
and refreshes them. Linear sends no webhook when someone archives an agent
session, so the hub checks each workspace for archived sessions once a minute.

Use **one Linear app per purpose**. Every factory assigned an app hears every
mention of it, so two factories that share one both act on the same mention.

## 1. Create the app in Linear

In Linear, open **Settings** → **API** → **OAuth applications** → **New** and
fill in the form:

* **Application icon** and **Application name**: what people see, and the
  name they mention.
* **Developer name**, **Developer URL** and **Description**: anything; Linear
  requires the URL only for public apps.
* **Redirect URIs**: enter your hub's address for now; you replace it in
  step 3.
* **GitHub username**: leave it empty.
* **Public**: leave it off, unless workspaces other than yours should connect
  to it.
* **Client credentials**: leave it off.
* **Webhooks**: turn it on. Enter your hub's address as the **Webhook URL**
  for now; you replace it in step 3. Copy the **Webhook signing secret** Linear
  shows below it now.
* Under the events, tick **Agent session events** in **App events**. Leave
  every other event off.

Create the app, then note its **Client ID** and **Client secret**.

## 2. Add the app to the hub

In the hub, under **Apps → Add app**, choose **Linear app**, and enter the
app's name as Linear shows it, its client ID, client secret and webhook
signing secret.

Keep the name the same as the app's name in Linear: it is the name people
mention, and agents are told it is their own. You can rename the app in
Linear's settings any time; then rename it on its page on the hub too.
Running factories learn the new name the next time they get a Linear token;
restart a factory to apply it at once.

## 3. Finish the app's settings

The app's page on the hub shows its **Redirect URI**, ending in
`/oauth/linear/<id>/callback`, and its **Webhook URL**, ending in
`/webhooks/linear/<id>`. Each Linear app has its own. In the app's settings
in Linear, replace the placeholder under **Redirect URIs** and the **Webhook
URL** with these.

## 4. Connect your workspace

On the app's page on the hub, choose **Connect a Linear workspace**. Linear
asks a workspace admin to approve the app; the hub asks for `read` and
`write`, and for the app to be mentionable and assignable, so it can work as
an agent. The workspace then appears under **Workspaces**. Give it an
[installation name](/guide/hub#installation-names), such as
`linear-acme`, under **Installation name**, and save.

If the hub can no longer refresh a workspace's tokens, for example because
the app was revoked in Linear, the workspace shows **Stopped working**. An
admin fixes it with **Connect it again**, next to the reason.

## 5. Assign it to factories

On the **Settings** tab of each factory that should act as this app, choose
**Connect app** and connect the app. A factory may be assigned several Linear
apps and workspaces, and names the installation it uses in each trigger, step
and agent.

In the factory, `pnpm exec jigs doctor` checks that the hub hands it a token
for each Linear installation it uses. To start runs from delegations and mentions, see
[Linear delegations and mentions](/guide/configuration#linear-agent-sessions).
To have Claude Code answer in Linear's agent panel, see
[Linear conversations](/guide/linear-conversations).