Summary

This page explains the Linear integration at a glance and the two integration directions:

Outbound (Nota → Linear): Nota uses a Linear API key to read issues, users, teams, and labels, and to post comments and file issues from workflow runs.
Inbound (Linear → Nota): Linear sends webhook events (comments, issues created/updated) into Nota to trigger workflows and produce in-thread replies.

Includes the required identifiers, a setup checklist, testing steps, and common troubleshooting scenarios.

➿ Linear (team feature)

Connecting Linear has two directions:

Outbound (Nota → Linear) — Nota reads issues and posts comments / files issues. Needs an API key.
Inbound (Linear → Nota) — @nota mentions in Linear comments get an in-thread reply, and new / assigned issues can auto-run your workflows. Needs a dedicated Nota account and a webhook.

Set up outbound first, then inbound.

For the full experience — where replies post as Nota and teammates can @-mention it — create the dedicated Nota account in the Inbound section first, then use its API key for the outbound field below. Linear attributes every API action to whichever account owns the key.

Outbound — let Nota act on your workspace

Step 1 — Create the Linear API key

Log in to your workspace at linear.app.
Click your profile name (top-left) → Settings.
Under Personal → Security & access, find Personal API keys.
Click New API key, name it, and choose permissions.
Click Create, then copy and save the key — Linear shows it only once. This is your Linear API Key.

Nota’s read tools (linearListIssues, linearSearchIssues, linearListTeams, …) work with a read-scoped key. But inbound @mention replies and issue-filing post comments/issues with this same key, so grant write access if you want those. Actions are attributed to the account that owns the key — create it as the dedicated Nota account (Inbound → Step 1) so replies appear under Nota.

Step 2 — Find your Team ID (the UUID)

Linear has two team identifiers and this field needs the UUID, not the short key:

Team key — the prefix in issue IDs, e.g. NTA in NTA-123. This is not what goes here.
Team UUID — a xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx string the Linear API requires. This is the value.

Entering the key produces teamId must be a UUID the moment Nota tries to file an issue (see Troubleshooting).

Get the UUID either way:

From the Linear API (needs only the key from Step 1):

curl -s https://api.linear.app/graphql \
  -H "Authorization: <YOUR_LINEAR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ teams { nodes { id key name } } }"}'

Copy the id (the UUID) of the team whose key matches yours. Linear’s Authorization header takes the raw key — no Bearer prefix.

From Nota chat (once the API key is saved in Step 3): ask “list my Linear teams” — Nota returns each team’s UUID, key, and name.

Step 3 — Configure Nota

Go to app.trynota.ai/integrations and click Linear Settings. Fill in:

Field	Value
Linear API Key	The key you saved in Step 1
Linear Team ID	The team UUID from Step 2 — not the `NTA`-style key

Click Update Settings — Nota uses it immediately, no redeploy needed. On save Nota also resolves and stores your Linear Organization ID automatically; that’s what routes inbound webhooks to your team later.

You’re done with outbound. In Nota chat, say “list my top 10 Linear issues” — you should see your issues. Then try “file a Linear ticket for the last failing run” — it should create an issue (this is the path that fails with teamId must be a UUID if Step 2 holds the key instead of the UUID).

Inbound — @nota mentions & issue events

For @nota mentions to work, Nota needs a real, mentionable Linear account. Teammates must be able to @-mention it, and Nota must be able to tell its own comments apart from users’ (so it never replies to itself).

Step 1 — Create a dedicated Nota account

Create (or reuse) an email for the bot, e.g. nota@<your-domain>.
In Linear → Settings → Members → Invite, invite that email to the workspace.
Accept the invite from that inbox, set the display name to Nota, and note its username / handle — the exact text after @ when you mention it (if the @-menu shows @nota, the handle is nota).

Step 2 — Note the two Nota identities

Linear uses different identifiers for the two inbound features. Grab whichever you need:

Inbound feature	Needs	Where to get it
New-issue auto-discovery	(neither)	Works from the webhook alone
@nota mention replies	Nota Bot Username (the `@`-handle)	The handle from Step 1, e.g. `nota`
Assignment-to-Nota detection	Nota Bot User ID (the UUID)	GraphQL query below

The bot user UUID (for assignment only) — Linear doesn’t show it in the UI:

# If the API key belongs to the bot account:
curl -s https://api.linear.app/graphql \
  -H "Authorization: <YOUR_LINEAR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ viewer { id name displayName email } }"}'

# Otherwise list users and pick the bot by name:
curl -s https://api.linear.app/graphql \
  -H "Authorization: <YOUR_LINEAR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ users { nodes { id name displayName email active } } }"}'

Mention detection reads the Nota Bot Username (the handle in the comment text), not the UUID. The Nota Bot User ID (UUID) drives assignment detection only. You can set just the username for mentions, just the UUID for assignment, or both.

Step 3 — Create the webhook in Linear

In Linear → Settings → API → Webhooks, click New webhook.

Set the URL to:

https://app.trynota.ai/api/webhooks/linear

Under data-change events, enable:
Event Why
✅ Comments @nota mentions in comments → in-thread reply
✅ Issues New-issue auto-discovery + assignment-to-Nota
Create. Linear generates a Signing secret — copy it (you paste it into Nota next).

Event	Why
✅ Comments	`@nota` mentions in comments → in-thread reply
✅ Issues	New-issue auto-discovery + assignment-to-Nota

Unlike GitLab, you don’t invent this secret — Linear generates it on webhook creation, and Nota HMAC-verifies every event against it.

Step 4 — Configure Nota

Back in app.trynota.ai/integrations → Linear Settings, fill in:

Field	Value
Nota Bot Username	The bot’s Linear `@`-handle, e.g. `nota` (a leading `@` is fine — it’s stripped). Required for mention replies.
Linear Webhook Signing Secret	The signing secret Linear generated in Step 3
Nota Bot User ID (optional)	The bot user UUID — enables assignment-to-Nota detection only. Leave blank if you only want mentions.

Click Update Settings.

Step 5 — Test it

Mention Nota from a different account. As yourself (not the Nota account), open a Linear issue, add a comment, and type the bot’s handle — @nota what does this issue cover?. Post it — Nota replies in-thread within a few seconds.Plain @nota text is detected; you don’t need the autocomplete chip. The @ must start the comment or follow a space (so an email like x@nota.com or a longer handle like @nota-bot is not treated as a mention).

Mention the bot from a human account, not as the bot. The loop guard drops any comment whose author is the Nota account, so if you configure your own handle and mention yourself, Nota stays silent by design (it must never reply to itself). Use the dedicated bot account’s handle and mention it from your normal account.

Comment edits are ignored — only newly-created comments trigger a reply (edited / removed comments are dropped before dispatch). Post a fresh comment rather than editing one.

Linear logs every delivery under Settings → API → Webhooks → your webhook → recent deliveries. A 200 {"status":"skipped"} means the event reached Nota but wasn’t a recognised mention (the handle wasn’t in the comment, or it was self-authored); a 202 Accepted means it dispatched.

Troubleshooting

Result	Cause	Fix
Issue-create fails `teamId must be a UUID`	Linear Team ID holds the team key (`NTA`) instead of the UUID	Replace it with the team UUID from Outbound Step 2 (`{ teams { nodes { id key name } } }`, or ask chat “list my Linear teams”)
Webhook 503 `integration not configured`	Signing secret not set in Nota (and no platform-wide secret)	Complete Inbound Step 4 with the secret Linear generated
Webhook 403 signature rejected	The Linear Webhook Signing Secret in Nota doesn’t match the webhook’s	Re-copy the signing secret from the Linear webhook into Nota
200 `unregistered_platform_workspace`	Organization ID didn’t bind	Re-save the API key (Outbound Step 3) — the org ID resolves from it
Mention posts but no reply	Mentioned Nota as the Nota account → dropped by the loop guard	Mention it from a different account
Comment ignored (no detection)	Nota Bot Username blank/wrong, or you mentioned a different handle	Set the bot’s exact `@`-handle; mention that handle (`@nota`), not the display name
Reply fails to post	The API key lacks write access, or it belongs to an account without comment permission	Use a write-scoped key owned by the Nota account

Quick isolation: run the { viewer { id } } GraphQL call (Inbound Step 2) with the bot’s key. A valid response = the key works and the problem is in Nota’s stored config. Treat the API key and signing secret like passwords — rotate them if you suspect either has leaked.

Get Started

View Artifacts

New Chat

Settings

Integrations

Linear

Summary

➿ Linear (team feature)

Outbound — let Nota act on your workspace

Step 1 — Create the Linear API key

Step 2 — Find your Team ID (the UUID)

Step 3 — Configure Nota

Inbound — @nota mentions & issue events

Step 1 — Create a dedicated Nota account

Step 2 — Note the two Nota identities

Step 3 — Create the webhook in Linear

Step 4 — Configure Nota

Step 5 — Test it

Troubleshooting

​Summary

​➿ Linear (team feature)

​Outbound — let Nota act on your workspace

​Step 1 — Create the Linear API key

​Step 2 — Find your Team ID (the UUID)

​Step 3 — Configure Nota

​Inbound — @nota mentions & issue events

​Step 1 — Create a dedicated Nota account

​Step 2 — Note the two Nota identities

​Step 3 — Create the webhook in Linear

​Step 4 — Configure Nota

​Step 5 — Test it

​Troubleshooting

Summary

➿ Linear (team feature)

Outbound — let Nota act on your workspace

Step 1 — Create the Linear API key

Step 2 — Find your Team ID (the UUID)

Step 3 — Configure Nota

Inbound — @nota mentions & issue events

Step 1 — Create a dedicated Nota account

Step 2 — Note the two Nota identities

Step 3 — Create the webhook in Linear

Step 4 — Configure Nota

Step 5 — Test it

Troubleshooting