---
name: bijection-convex-linear
description: "Evaluate and integrate the Convex Linear component with Bijection."
---

# Convex Linear

Sync Linear issues and comments into Convex reactively, and create, update, comment on, and archive issues from Convex functions.

This is an upstream package. It has not been adapted or qualified for Bijection.

- Package: convex-linear
- Source: https://github.com/sholajegede/convex-linear
- npm: https://www.npmjs.com/package/convex-linear
- Directory: https://bijection.com/components/convex-linear

Read the upstream README for setup, license, and compatibility before using it.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes convex-linear. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses Convex Linear. Follow the installation and configuration steps exactly.

# Convex Linear

## Instructions

convex-linear keeps a live, queryable mirror of Linear issues and comments inside your Convex deployment, updated in real time via verified webhooks. It also exposes actions for creating, updating, commenting on, archiving, and unarchiving issues directly through Linear's GraphQL API. The component's tables live in an isolated schema so they do not conflict with your app's own data model.

### Installation

```bash
npm install convex-linear
```

Current npm version: `convex-linear@0.0.5`

## Use cases

- Building an internal tool that displays your team's Linear backlog reactively in a React app without polling or manual refresh
- Automating issue triage or creation from Convex functions, such as filing a bug report when an error threshold is crossed in your backend
- Syncing Linear issue state into Convex so you can join it with your own app data in queries, for example showing a user their support ticket's current workflow state
- Triggering Linear comments or priority updates from Convex mutations in response to application events, like escalating an issue when a customer's SLA window closes
- Auditing every webhook delivery from Linear with idempotent, signature-verified processing stored in Convex for replay and debugging

## How it works

Setup requires three steps: registering the component in `convex.config.ts` with `app.use(convexLinear)`, instantiating a `Linear` client with your `LINEAR_API_KEY` and `LINEAR_WEBHOOK_SECRET`, and mounting `linear.webhookHandler` on an HTTP route in `convex/http.ts`. You then point a Linear workspace webhook at `https://<your-deployment>.convex.site/webhooks/linear` and subscribe to Issues and Comments resource types.

Every inbound webhook delivery is verified against the `Linear-Signature` header using a constant-time HMAC-SHA256 comparison and rejected if the `Linear-Timestamp` is more than 60 seconds old. Deliveries are deduplicated by `Linear-Delivery` ID. For Issue events, the handler re-fetches the issue's current state from Linear's GraphQL API on every delivery rather than branching on the `action` field, because `action` does not reliably distinguish archived, trashed, and deleted states. A row is only hard-deleted when the re-fetch returns "Entity not found".

Query methods (`getIssue`, `listIssuesByTeam`, `listCommentsByIssue`) can be called from Convex queries, mutations, or actions and are suitable for use with `useQuery` in React for reactive updates. Write operations (`createIssue`, `updateIssue`, `createComment`, `archiveIssue`, `unarchiveIssue`) are actions that call Linear's GraphQL API and immediately record the result in Convex, so callers see the updated data without waiting for the subsequent webhook round-trip.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Convex Linear is not needed

## Resources

- [npm package](https://www.npmjs.com/package/convex-linear)
- [GitHub repository](https://github.com/sholajegede/convex-linear)
- [Live demo](https://convex-linear.vercel.app)
- [Convex Components Directory](https://www.convex.dev/components/convex-linear)
- [Convex documentation](https://docs.convex.dev)