---
sidebar_position: 3
title: Linear Integration
---

# Linear Integration

Connect Linear so your agents can read and update issues, comments, and workflow states. Linear uses a **personal API key** — no OAuth round-trip.

## How It Works

You paste a single Linear personal API key. Zibby validates it (by querying the authenticated viewer) before storing it, then the `linear` skill exposes Linear's API to any node that declares it.

## Connect Linear

1. In Linear, go to **Settings → Security & access → Personal API keys**
2. Create a new key — it has the form `lin_api_...`
3. In the Zibby dashboard, go to **Settings → Integrations** and click **Connect Linear**
4. Paste the key and click **Connect**

That's it — one field. Zibby verifies the key against Linear's GraphQL API before saving.

## What Agents Can Do

Once connected, nodes that attach the [`linear` skill](../skills/index.md) get these tools:

| Tool | What it does |
|---|---|
| `linear_list_issues` | List issues (filter by team, state, assignee, label) |
| `linear_get_issue` | Fetch one issue with full detail |
| `linear_add_comment` | Comment on an issue |
| `linear_update_state` | Move an issue to a different workflow state |
| `linear_list_teams` / `linear_list_states` / `linear_list_labels` | Resolve names → IDs for the calls above |

## Reference key (SDK / CLI)

When running agents directly (local or CI), the same connector reads from the `LINEAR_API_KEY` environment variable instead of the dashboard-stored credential.

## Troubleshooting

**"Invalid API key"** — regenerate the key in Linear (Settings → Security & access → Personal API keys) and reconnect. Keys are revoked when you remove them from Linear.

**Agent can't find a team/state** — call `linear_list_teams` / `linear_list_states` first; Linear's API keys are scoped to whatever the issuing user can see.