> ## Documentation Index
> Fetch the complete documentation index at: https://learn.actionist.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Linear

> Connect Linear to Actionist and let agents create issues, manage sprints, and keep your backlog clean — triggered by any signal, no tab-switching required.

<div className="mxp-hero xc-border">
  <div className="exp-eyebrow mxp-rise">LINEAR INTEGRATION</div>

  <h2 className="mxp-hero-title mxp-rise" style={{animationDelay:'0.06s'}}>
    Issue tracking at the speed your team <span style={{background:'linear-gradient(90deg,#24A4FF,#9000FF,#E3008E)',WebkitBackgroundClip:'text',backgroundClip:'text',color:'transparent'}}>actually ships.</span>
  </h2>

  <p className="mxp-hero-dek mxp-rise" style={{animationDelay:'0.13s'}}>
    Any signal — a Sentry alert, a Slack message, a customer email, a form submission — becomes a properly-formed Linear issue in under 60 seconds, with team, priority, assignee, and description pre-filled. Sprint admin disappears. Backlog hygiene runs on a schedule. Your team keeps shipping; Actionist keeps the board clean.
  </p>
</div>

<div className="w-full py-10">
  <div className="actionist-tight flex flex-col gap-2 mb-6">
    <span className="actionist-section-eyebrow">Watch it happen</span>
    <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-gray-900 dark:text-gray-50">An issue — from chat to closed.</h2>

    <p className="text-base text-gray-600 dark:text-gray-400 max-w-3xl">
      The full lifecycle: an issue created from a Slack message, its status updated mid-sprint, and a final comment linking back to the fix. Pick an event to step through it.
    </p>
  </div>

  <div className="xali-stream-shell exp-tool-shell xc-try">
    <div className="mxp-srch-chips">
      <label htmlFor="xali-e1"><input className="mxp-r" type="radio" name="xali-ev" id="xali-e1" defaultChecked />Issue created from chat</label>
      <label htmlFor="xali-e2"><input className="mxp-r" type="radio" name="xali-ev" id="xali-e2" />Status updated</label>
      <label htmlFor="xali-e3"><input className="mxp-r" type="radio" name="xali-ev" id="xali-e3" />Comment added</label>
    </div>

    <div className="xali-panel xali-p1">
      <div className="mxp-window">
        <div className="mxp-window-bar">
          <span className="mxp-window-dot" />

          <span className="mxp-window-dot" />

          <span className="mxp-window-dot" />

          <span className="mxp-window-title">chat · maya · 10:41</span>
        </div>

        <div className="mxp-window-body" style={{minHeight:'auto',padding:'14px 18px'}}>
          <div className="mxp-stream-line mxp-s1"><span className="mxp-stream-time">you</span><span className="mxp-stream-text">There's a checkout bug from Sentry — create a Linear issue for the eng team, high priority.</span></div>
          <div className="mxp-s2" style={{margin:'8px 0'}}><span className="mxp-stream-event">tool · linear\_create\_issue</span></div>
          <div className="mxp-stream-line mxp-s3"><span className="mxp-stream-time">maya</span><span className="mxp-stream-text">Created <em>ENG-412 — Checkout fails on coupon apply</em> · team: Engineering · priority: <em>high</em> · assigned: on-call.</span></div>
          <div className="mxp-stream-line mxp-s4"><span className="mxp-stream-time">maya</span><span className="mxp-stream-text">Sentry event ID and stack trace added to description. Link: <em>linear.app/eng/ENG-412</em><span className="mxp-caret" /></span></div>
        </div>
      </div>

      <div className="xali-annotation">
        <em>linear\_create\_issue</em> — title, team, description (Markdown), assignee, priority (integer), and state all set in one call. The Sentry context lands in the issue body and renders natively in Linear's editor.
      </div>
    </div>

    <div className="xali-panel xali-p2">
      <div className="mxp-window">
        <div className="mxp-window-bar">
          <span className="mxp-window-dot" />

          <span className="mxp-window-dot" />

          <span className="mxp-window-dot" />

          <span className="mxp-window-title">workflow · sprint-sync · 14:05</span>
        </div>

        <div className="mxp-window-body" style={{minHeight:'auto',padding:'14px 18px'}}>
          <div className="mxp-stream-line mxp-s1"><span className="mxp-stream-time">sched</span><span className="mxp-stream-text">PR #881 merged to main. Branch: <em>fix/ENG-412-coupon-checkout</em>.</span></div>
          <div className="mxp-s2" style={{margin:'8px 0'}}><span className="mxp-stream-event">tool · linear\_get\_issue · ENG-412</span></div>
          <div className="mxp-s3" style={{margin:'8px 0'}}><span className="mxp-stream-event">tool · linear\_update\_issue · state: In Review</span></div>
          <div className="mxp-stream-line mxp-s4"><span className="mxp-stream-time">agent</span><span className="mxp-stream-text"><em>ENG-412</em> moved from <em>In Progress</em> to <em>In Review</em>. Priority unchanged: high.<span className="mxp-caret" /></span></div>
        </div>
      </div>

      <div className="xali-annotation">
        <em>linear\_update\_issue</em> accepts the human-readable identifier (<em>ENG-412</em>) — no UUID lookup needed when the reference comes from a PR branch name or commit message.
      </div>
    </div>

    <div className="xali-panel xali-p3">
      <div className="mxp-window">
        <div className="mxp-window-bar">
          <span className="mxp-window-dot" />

          <span className="mxp-window-dot" />

          <span className="mxp-window-dot" />

          <span className="mxp-window-title">workflow · issue-close · 16:22</span>
        </div>

        <div className="mxp-window-body" style={{minHeight:'auto',padding:'14px 18px'}}>
          <div className="mxp-stream-line mxp-s1"><span className="mxp-stream-time">sched</span><span className="mxp-stream-text">Deploy succeeded — <em>v2.14.1</em> live. Affected issue: ENG-412.</span></div>
          <div className="mxp-s2" style={{margin:'8px 0'}}><span className="mxp-stream-event">tool · linear\_add\_comment · ENG-412</span></div>
          <div className="mxp-s3" style={{margin:'8px 0'}}><span className="mxp-stream-event">tool · linear\_update\_issue · state: Done</span></div>
          <div className="mxp-stream-line mxp-s4"><span className="mxp-stream-time">agent</span><span className="mxp-stream-text">Commented: <em>"Fixed in v2.14.1 — deploy verified. Sentry event resolved."</em> Issue closed.<span className="mxp-caret" /></span></div>
        </div>
      </div>

      <div className="xali-annotation">
        <em>linear\_add\_comment</em> keeps the full audit trail in Linear itself — Sentry ID, deploy tag, and verification note — without any manual copy-paste. The issue history is self-documenting.
      </div>
    </div>
  </div>
</div>

<div className="w-full py-10 xc-rise">
  <div className="actionist-tight flex flex-col gap-2 mb-6">
    <span className="actionist-section-eyebrow">Capabilities</span>
    <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-gray-900 dark:text-gray-50">What agents can do with Linear.</h2>

    <p className="text-base text-gray-600 dark:text-gray-400 max-w-3xl">
      Seven scopes across the full issue lifecycle — from reading your workspace to writing issues, updates, and comments.
    </p>
  </div>

  <div>
    <div className="xali-tool-row">
      <div className="xali-tool-icon">☰</div>

      <div className="xali-tool-body">
        <strong>Read teams and projects</strong>
        <span>List every team and project in your Linear workspace. Fetch project IDs at workflow setup time and cache them as variables so agents don't re-fetch on every run.</span>
      </div>

      <span className="xali-tool-mono">linear\_list\_teams</span>
    </div>

    <div className="xali-tool-row">
      <div className="xali-tool-icon">☷</div>

      <div className="xali-tool-body">
        <strong>List and filter issues</strong>
        <span>Pull issues filtered by team, state, assignee, or project. Narrow by team first to reduce query cost, then layer on additional filters.</span>
      </div>

      <span className="xali-tool-mono">linear\_list\_issues</span>
    </div>

    <div className="xali-tool-row">
      <div className="xali-tool-icon">☌</div>

      <div className="xali-tool-body">
        <strong>Get a single issue</strong>
        <span>Fetch a specific issue by its human-readable identifier (e.g. <code>ENG-123</code>) or internal UUID. Prefer the identifier in workflows where issue references come from Slack messages, PR branch names, or commit messages.</span>
      </div>

      <span className="xali-tool-mono">linear\_get\_issue</span>
    </div>

    <div className="xali-tool-row">
      <div className="xali-tool-icon">+</div>

      <div className="xali-tool-body">
        <strong>Create issues</strong>
        <span>Create issues with title, team, description (Markdown), assignee, priority, and state — all from a single agent step. Pass Markdown in <code>description</code> and it renders natively in Linear's editor.</span>
      </div>

      <span className="xali-tool-mono">linear\_create\_issue</span>
    </div>

    <div className="xali-tool-row">
      <div className="xali-tool-icon">✎</div>

      <div className="xali-tool-body">
        <strong>Update issues</strong>
        <span>Change title, description, assignee, priority, or state on any existing issue. Useful for backlog hygiene sweeps and sprint-boundary automations.</span>
      </div>

      <span className="xali-tool-mono">linear\_update\_issue</span>
    </div>

    <div className="xali-tool-row">
      <div className="xali-tool-icon">☺</div>

      <div className="xali-tool-body">
        <strong>Add comments</strong>
        <span>Post a top-level comment or thread a reply using <code>parentId</code>. Keeps issue history clean and links back to source context — Sentry IDs, Slack thread URLs, deal notes.</span>
      </div>

      <span className="xali-tool-mono">linear\_add\_comment</span>
    </div>
  </div>
</div>

<div className="w-full py-10 xc-rise">
  <div className="actionist-tight flex flex-col gap-2 mb-6">
    <span className="actionist-section-eyebrow">Setup</span>
    <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-gray-900 dark:text-gray-50">Connect Linear.</h2>

    <p className="text-base text-gray-600 dark:text-gray-400 max-w-3xl">
      MCP OAuth is the recommended path — no token management, full action set, and you can limit which Linear teams are exposed during the OAuth step. API key is available as a fallback.
    </p>
  </div>

  <Steps>
    <Step title="Open Apps and find Linear">
      Click <strong>Apps</strong> in the sidebar. Find Linear in the apps library and click <strong>Connect Linear</strong>.
    </Step>

    <Step title="Choose a connection method">
      <Tabs>
        <Tab title="MCP OAuth (recommended)" icon="plug">
          A Linear OAuth window opens in your browser. Sign in with your Linear account and grant Actionist read/write access. Actionist runs a <strong>Test connection</strong> call to verify the handshake. Status updates to <strong>Connected</strong> and the app detail page shows the scope count granted.
        </Tab>

        <Tab title="API key" icon="key">
          In Linear, go to <strong>Settings → Security & access → Personal API keys</strong>. Click <strong>Create key</strong>, name it (e.g. "Actionist"), and copy the token — it is shown only once.

          Back in Actionist, open Linear → <strong>Connection methods</strong>, select <strong>API key</strong>, paste the token, and click <strong>Test connection</strong>.
        </Tab>
      </Tabs>
    </Step>

    <Step title="Confirm the connection">
      Once status shows <strong>Connected</strong>, Linear tools are available to every agent and workflow in your workspace.
    </Step>
  </Steps>

  {/* TODO(image): linear-connect-oauth — IMAGE SPEC: The Linear app detail page in the Actionist Apps tab. Show the 'Connect Linear' button with 'Not connected' status label visible, and the Connection methods section with MCP selected and marked recommended. The OAuth window modal should be partially visible in the background, beginning to open. Dark background, scope count badge visible. — replace this CSS mock with the real screenshot */}

  <div className="xali-mock-oauth">
    <div className="mxp-window xali-mock-window">
      <div className="mxp-window-bar">
        <span className="mxp-window-dot" />

        <span className="mxp-window-dot" />

        <span className="mxp-window-dot" />

        <span className="mxp-window-title">actionist · Apps · Linear</span>
        <span className="xali-priority xali-mock-badge-red">Not connected</span>
      </div>

      <div className="mxp-window-body xali-mock-body">
        <div className="xali-mock-app-header">
          <div className="xali-mock-app-icon">L</div>

          <div className="xali-mock-app-meta">
            <strong>Linear</strong>
            <span>Issue tracking · 6 scopes granted</span>
          </div>

          <div className="xali-mock-connect-btn">Connect Linear</div>
        </div>

        <div className="xali-mock-divider" />

        <div className="xali-mock-section-label">Connection method</div>

        <div className="mxp-mock-row xali-mock-row-selected">
          <div className="xali-mock-radio xali-mock-radio-on" />

          <div className="xali-mock-row-body">
            <strong>MCP OAuth</strong>
            <span>No token management — recommended</span>
          </div>

          <span className="xali-priority xali-mock-badge-purple">Recommended</span>
        </div>

        <div className="mxp-mock-row">
          <div className="xali-mock-radio" />

          <div className="xali-mock-row-body">
            <strong>API key</strong>
            <span>Paste a Personal Access Token</span>
          </div>
        </div>
      </div>
    </div>

    <div className="xali-mock-oauth-modal">
      <div className="mxp-window-bar xali-mock-oauth-bar">
        <span className="mxp-window-dot" />

        <span className="mxp-window-dot" />

        <span className="mxp-window-dot" />

        <span className="xali-mock-oauth-title">linear.app — Authorize Actionist</span>
      </div>

      <div className="xali-mock-oauth-body">
        <div className="xali-mock-oauth-logo">L</div>
        <div className="xali-mock-oauth-prompt">Actionist is requesting access to your Linear workspace</div>
        <div className="xali-mock-oauth-scope"><span className="xali-mock-scope-chip">read:issues</span><span className="xali-mock-scope-chip">write:issues</span><span className="xali-mock-scope-chip">read:teams</span></div>
        <div className="xali-mock-oauth-cta">Authorize</div>
      </div>
    </div>
  </div>
</div>

<div className="w-full py-10 xc-rise">
  <div className="actionist-tight flex flex-col gap-2 mb-6">
    <span className="actionist-section-eyebrow">Workflows</span>
    <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-gray-900 dark:text-gray-50">Common workflows to start with.</h2>
  </div>

  <div className="mxs-tiers" style={{gridTemplateColumns:'repeat(auto-fit,minmax(270px,1fr))',gap:'14px',marginTop:'4px'}}>
    <div className="mxs-tier" data-accent="purple">
      <span className="tag">Engineering</span>
      <strong>Bug-to-fix loop</strong>
      <p>A Sentry alert fires, an agent creates a Linear issue with the error context in the description, assigns it to the on-call engineer, and comments with the Sentry link — before anyone checks their inbox.</p>
    </div>

    <div className="mxs-tier" data-accent="blue">
      <span className="tag">Engineering</span>
      <strong>Sprint retro, auto-compiled</strong>
      <p>When a Linear sprint (Cycle) ends, an agent collects all closed issues, groups them by owner, and posts the retro summary to Slack before anyone opens Linear.</p>
    </div>

    <div className="mxs-tier" data-accent="green">
      <span className="tag">Sales and support</span>
      <strong>Zero-tab issue creation</strong>
      <p>A closed-deal message lands in Slack. The agent reads the feature gap, creates a Linear issue in the right team with ARR context attached, and links it back to the deal record — no tab-switching, no copy-paste.</p>
    </div>

    <div className="mxs-tier" data-accent="green">
      <span className="tag">Sales and support</span>
      <strong>Customer need from escalation</strong>
      <p>A Support agent creates a customer need issue from an escalation ticket, assigns it to the product team, and comments with the original customer message.</p>
    </div>

    <div className="mxs-tier" data-accent="orange">
      <span className="tag">Operations</span>
      <strong>Backlog hygiene sweep</strong>
      <p>A scheduled agent runs weekly: updates stale priorities, sweeps blocked issues, and adds audit comments — what used to take 30 minutes of clicking completes in under a minute.</p>
    </div>

    <div className="mxs-tier" data-accent="orange">
      <span className="tag">Operations</span>
      <strong>Launch issue from campaign start</strong>
      <p>When a campaign brief is approved in Notion, an agent auto-creates a launch checklist issue in Linear and assigns it to the relevant project.</p>
    </div>
  </div>
</div>

<div className="w-full py-10 xc-rise">
  <div className="actionist-tight flex flex-col gap-2 mb-6">
    <span className="actionist-section-eyebrow">In practice</span>
    <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-gray-900 dark:text-gray-50">Three recipes teams run every day.</h2>

    <p className="text-base text-gray-600 dark:text-gray-400 max-w-3xl">
      Real workflows, concrete outputs — each one live in under 10 minutes.
    </p>
  </div>

  <div className="xc-recipes">
    <div className="xc-recipe">
      <div className="xc-recipe-who">
        <i style={{background:'linear-gradient(135deg,#486EFF,#9000FF)'}} />

        Sam · Solo founder
      </div>

      <div className="xc-recipe-flow">
        Every morning at 08:55, an agent runs <em>linear\_list\_issues</em> filtered to <em>In Progress</em> and <em>In Review</em> across all teams, groups them by assignee, and posts a standup digest to Slack before the 09:00 call. Yesterday's 14 open issues, owners listed, blockers flagged — no one opens Linear just to read the board.
      </div>

      <span className="xc-recipe-save">saves \~20 min/day</span>
    </div>

    <div className="xc-recipe">
      <div className="xc-recipe-who">
        <i style={{background:'linear-gradient(135deg,#4ED8A7,#24A4FF)'}} />

        Priya · Support lead
      </div>

      <div className="xc-recipe-flow">
        When a support thread hits a <em>bug-confirmed</em> label in the helpdesk, the agent reads the conversation, calls <em>linear\_create\_issue</em> with a structured description — repro steps, affected version, customer count — and comments back on the ticket with the Linear link. 23 issues filed last week, zero copy-paste.
      </div>

      <span className="xc-recipe-save">saves \~3 hrs/wk</span>
    </div>

    <div className="xc-recipe">
      <div className="xc-recipe-who">
        <i style={{background:'linear-gradient(135deg,#24A4FF,#6C37FF)'}} />

        Dario · Sales
      </div>

      <div className="xc-recipe-flow">
        At cycle close, the agent calls <em>linear\_list\_issues</em> filtered to <em>Done</em> in the current cycle, groups by project, and drafts release notes as a Markdown doc — customer-facing language, no jargon. Dario pastes it into the deal room for prospects asking “what shipped this sprint?” — answered before the question lands.
      </div>

      <span className="xc-recipe-save">live in 10 min</span>
    </div>
  </div>
</div>

<div className="w-full py-10 xc-rise">
  <div className="actionist-tight flex flex-col gap-2 mb-6">
    <span className="actionist-section-eyebrow">Limits</span>
    <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-gray-900 dark:text-gray-50">Limits and gotchas.</h2>
  </div>

  <div className="mxs-limits">
    <div className="mxs-limit"><b>25</b><span>items returned per list call (teams, projects, issues)</span></div>
    <div className="mxs-limit"><b>0</b><span>priority = none; 1 = urgent; 2 = high; 3 = normal; 4 = low</span></div>
    <div className="mxs-limit"><b>1</b><span>writer per bucket recommended — avoid multi-agent contention on the same issue</span></div>
    <div className="mxs-limit"><b>ENG-123</b><span>prefer human-readable identifier over UUID in cross-system references</span></div>
  </div>

  <AccordionGroup>
    <Accordion title="List tools return 25 items by default" icon="list">
      All list tools (teams, projects, issues) paginate at 25 items per call. Filter by team, state, assignee, or project to narrow the result set before fetching. Filter by <code>teamId</code> first — it reduces query cost and keeps responses faster.
    </Accordion>

    <Accordion title="Priority is a number, not a label" icon="chart-column">
      When creating or updating issues, priority is an integer: <code>0</code> = none, <code>1</code> = urgent, <code>2</code> = high, <code>3</code> = normal, <code>4</code> = low. Spell these out in workflow instructions so agents always set the right value. Priority <code>1</code> (urgent) suits on-call assignment workflows; <code>4</code> (low) suits backlog items that surface only in sprint planning.

      <div className="flex flex-wrap gap-2 mt-3">
        <span className="xali-priority xali-p-urgent">1 — urgent</span>
        <span className="xali-priority xali-p-high">2 — high</span>
        <span className="xali-priority xali-p-normal">3 — normal</span>
        <span className="xali-priority xali-p-low">4 — low</span>
      </div>
    </Accordion>

    <Accordion title="Use the identifier, not the UUID" icon="hash">
      Issue fetch and update actions accept either the human-readable identifier (e.g. <code>ENG-123</code>) or the internal UUID. Prefer the identifier in workflows where issue references come from Slack messages, PR branch names, or commit messages — those almost always carry the short form. Use <code>identifier</code> (returned by all issue queries) when posting links to external systems; it is the stable public handle.
    </Accordion>

    <Accordion title="Prevent agent-write trigger loops" icon="rotate-ccw">
      If an agent creates or updates issues and you have a trigger on issue changes, the agent's writes will re-fire the trigger. Stamp a custom label on every agent-touched issue and exclude that label from your trigger filter conditions.
    </Accordion>
  </AccordionGroup>

  <Tip>
    Use the MCP OAuth path over the API key path — no token to rotate, full action set, and you can limit which teams are exposed at OAuth time. To restrict access to specific teams, do it during the OAuth step; you cannot reduce team scope later without disconnecting and reconnecting.
  </Tip>
</div>

<div className="w-full py-10">
  <div className="actionist-cta-panel xc-border">
    <div className="relative z-10 flex flex-col items-center gap-5 max-w-2xl mx-auto">
      <span className="actionist-eyebrow">Automate the board</span>

      <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-white leading-tight">
        Your team ships. Actionist keeps Linear clean.
      </h2>

      <p className="text-base md:text-lg text-white/85">
        Connect Linear in two minutes. Let agents handle issue creation, status updates, and backlog hygiene — triggered by every signal your team already produces.
      </p>

      <div className="flex flex-wrap items-center justify-center gap-3 pt-2">
        <a className="actionist-cta-btn-primary" href="https://app.actionist.ai" target="_blank" rel="noreferrer">
          Open the Dashboard

          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.2" strokeLinecap="round" strokeLinejoin="round">
            <path d="M5 12h14" />

            <path d="m12 5 7 7-7 7" />
          </svg>
        </a>

        <a className="actionist-cta-btn-secondary" href="mailto:support@actionist.ai">
          Email the team
        </a>
      </div>
    </div>
  </div>
</div>

<div className="w-full pt-2 pb-6">
  <p className="actionist-trust-line">
    MCP OAuth — no token to rotate, full action set, team-scoped at connect time.<br />
    Issues created in under 60 seconds · Runs on any signal · Backlog hygiene on a schedule.
  </p>
</div>

<div className="w-full pb-16">
  <div className="actionist-tight flex flex-col gap-2 mb-6">
    <span className="actionist-section-eyebrow">Keep going</span>
    <h2 className="text-2xl md:text-3xl font-semibold tracking-tight text-gray-900 dark:text-gray-50">Related topics.</h2>
  </div>

  <Columns cols={3}>
    <Card title="Slack" icon="https://cdn.simpleicons.org/slack" href="/apps/slack">
      Linear and Slack together cover most team automation loops — bug alerts, retro summaries, and approval flows.
    </Card>

    <Card title="MCP" icon="plug" href="/Folders/mcp">
      How the Linear MCP server fits into the broader integration model and how to manage OAuth scopes.
    </Card>

    <Card title="Reactions" icon="zap" href="/Folders/reactions">
      Wire Linear webhook triggers — new issues, comments, and cycle events — to agents with filter rules and routing.
    </Card>

    <Card title="Schedules" icon="calendar-clock" href="/Folders/schedules">
      Set up recurring agent runs for backlog hygiene sweeps, sprint retros, and cycle-boundary automations.
    </Card>

    <Card title="Credentials" icon="key" href="/Folders/credentials">
      Store and rotate Linear API keys in the encrypted Credentials Vault without re-editing agents.
    </Card>

    <Card title="Apps" icon="layout-grid" href="/apps">
      Browse every app Actionist connects to — and see what else fits in your workflow alongside Linear.
    </Card>
  </Columns>
</div>