Linear App Setup

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

assistant/CLAUDE.md

assistant/src/approvals/CLAUDE.md

assistant/src/notifications/CLAUDE.md

assistant/src/runtime/CLAUDE.md

gateway/CLAUDE.md

Audit 0.4.1 · source sha 19bc86343b63 · 14 Oct 2026Report an issue or request a re-scan

• Publishervellum-ai GitHub organizationOwner of the repository this skill is read from
• Source foldervellum-ai/vellum-assistant/skills/linear-app-setupThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict19bc86343b63A new audit runs when the source changes
• Repository statusNot archivedLast push 1 day ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Create and configure a Linear agent app so the assistant can manage issues, projects, and workflows under its own identity

---
name: linear-app-setup
description: Create and configure a Linear agent app so the assistant can manage issues, projects, and workflows under its own identity
compatibility: "Designed for Vellum personal assistants"
metadata:
  icon: assets/icon.svg
  emoji: "🔷"
  vellum:
    category: "development"
    display-name: "Linear App Setup"
    user-invocable: true
---

## Overview

Set up a **Linear agent app** so the assistant operates under its own identity in a Linear workspace — creating issues, commenting, updating status, etc. as itself.

Linear agent apps act as their own entity in the workspace. They're free (don't count as billable users), can be @mentioned, and can be delegated issues.

**Total manual effort: ~3 interactions** — create the app, grab the API key, (optionally) upload an avatar.

## Prerequisites

- User must be a **workspace admin** in Linear
- User must be logged into Linear in their browser

## Setup Flow

### Step 1: Create the Application

Direct the user to create a new application:

> Open **https://linear.app/settings/api/applications/new** to create a new application.

Guide them through the form:

| Field                | Value                                                                        |
| -------------------- | ---------------------------------------------------------------------------- |
| **Application name** | The assistant's name. This is how the agent appears in mentions and filters. |
| **Developer name**   | The user's name or org name                                                  |
| **Developer URL**    | Any valid URL                                                                |

> Click **Create** when done.

### Step 2: Generate an API Key for the App

After creating the app, the user should generate a **personal API key** scoped to this app identity. This is how the assistant authenticates — simpler and more reliable than the full OAuth token refresh flow.

Direct the user:

> On the app's settings page, look for the option to create an API key for this application. Copy the key.

Prompt for the API key via secure UI:

```bash
assistant credentials prompt --service linear --field api_key \
  --label "Linear App API Key" \
  --placeholder "lin_api_xxxxxxxxxx" \
  --description "API key for your Linear app (used to authenticate API requests)" \
  --allowed-domains "api.linear.app" \
  --allowed-tools "bash" \
  --injection-templates '[{"hostPattern":"api.linear.app","injectionType":"header","headerName":"Authorization","valuePrefix":"Bearer "}]'
```

### Step 3: Verify

After storing the key, verify the connection:

```bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"{ viewer { id name email } }"}'
```

Run with `network_mode: "proxied"` and the linear credential. A successful response returns the app's identity:

```json
{
  "data": {
    "viewer": {
      "id": "...",
      "name": "MyAssistant",
      "email": "[email protected]"
    }
  }
}
```

The `@oauthapp.linear.app` email confirms it's an app actor, not a user.

### Step 4: Set the App Avatar (Optional)

Linear doesn't support setting the avatar via API — it must be uploaded through the web UI.

If the assistant has an avatar, send it to the user:

```
<vellum-attachment source="sandbox" path="data/avatar/avatar-image.png" />
```

Then direct them to the app settings page:

> Go to **https://linear.app/settings/api**, find your app, and upload the avatar image under the app icon.

## App Identity

The app appears as a distinct entity in Linear:

- Issues it creates show the app as creator
- Comments it posts show the app's name and avatar
- It appears in mention menus if `app:mentionable` scope is enabled
- Issues can be delegated to it if `app:assignable` scope is enabled — delegation sets the app as `delegate`, not `assignee`, so humans keep ownership

### Acting on Behalf of a User

When the agent performs an action that originated from a specific user in a third-party system, use `createAsUser` and `displayIconUrl` to attribute it:

```graphql
mutation {
  issueCreate(
    input: {
      title: "Bug report"
      teamId: "TEAM_UUID"
      createAsUser: "Jane"
      displayIconUrl: "https://example.com/jane-avatar.png"
    }
  ) {
    success
    issue {
      identifier
      url
    }
  }
}
```

This renders as "Jane (via AppName)" in Linear.

## Team Access

After installation, workspace admins can modify the app's team access at any time through the app's details page in Linear settings.

## Important Notes

- The app's name and icon are how it appears everywhere in Linear — pick something short, recognizable, and unique.
- Agent apps are free — they don't count toward the workspace's billable user seats.
- The app gets a unique user ID per workspace.

Excerpt, first 4,837 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/vellum-ai/vellum-assistant
git -C vellum-assistant checkout 19bc86343b63

Works in

1. 2026-10-14
   ✓SAFE B 89 / 100

   first audit · source 19bc86343b63

Questions about Linear App Setup

• github.com/vellum-ai/vellum-assistant/tree/main/skills/linear-ap — the audited source at commit 19bc86343b63 and every finding aboveObserved · 14 Oct 2026

Spotted something wrong? Report a correction · Methodology