# Linear

Open a Linear issue from each submission.

## Linear

Turn submissions into Linear issues automatically. Each submission creates one issue in the team you choose, with a custom title, description, and project.

<h2 id="what-you-get">What you get</h2>

<ul>
  <li>One Linear issue per submission, attributed to the connecting user</li>
  <li>
    Title and description built from a template editor — type <strong>@</strong> to insert any form field value
  </li>
  <li>Description supports markdown (bold, lists, headings, code fences, block quotes, links)</li>
  <li>Optional default project applied to every issue</li>
  <li>Backfill existing submissions on demand (~1 issue per second)</li>
  <li>
    Test button that creates a real <code>[Test]</code>-prefixed issue so you can verify before going live
  </li>
</ul>

<h2 id="connect">Connect Linear</h2>

<h2 id="backfill">Backfill existing submissions</h2>

<p>
  When you first connect, you can export existing submissions as Linear issues. The backfill runs in the background at ~1 issue per second
  to stay within Linear's rate limits. Progress is logged every 10 submissions.
</p>

<h2 id="abandoned-responses">Abandoned response events</h2>

<p>
  When a respondent starts your form but doesn't finish, formbase can create a separate issue for the partial data. Set{' '}
  <strong>Send abandoned event after</strong> to 12 hours, 1 day, 3 days, or 1 week, then fill in the abandoned issue title and description
  — neither can be empty. Abandoned issues get a <code>partial-submission</code> label.
</p>

<p>
  An hourly sweep looks for idle drafts, so the issue appears at the first sweep after the window passes. Only drafts from a share link are
  swept, and <strong>Required fields</strong> narrows it further: the issue is created only when at least one of the fields you pick was
  filled in.
</p>

> ℹ️ **Pro feature**
> <p>
>     Abandoned response delivery requires a Pro or Business plan. The core Linear integration is available on all plans. See{' '}
>     <a href="/subscription-billing/plans-pricing">plans & pricing</a>.
>   </p>

<h2 id="token-refresh">Token refresh</h2>

<p>
  Linear access tokens refresh automatically before each dispatch when close to expiry. If refresh fails (token revoked, app uninstalled),
  formbase marks the integration as error and you receive a failure notification email. Reconnect from the workspace Integrations page to
  restore.
</p>

<h2 id="removing">Removing the integration</h2>

<ul>
  <li>
    <strong>From formbase</strong> — Form settings → Integrations → Linear → Delete. New submissions stop creating issues immediately.
  </li>
  <li>
    <strong>From Linear</strong> — Revoke the OAuth grant from your user settings. The next dispatch fails and the credential is marked
    expired.
  </li>
</ul>

<h2 id="limits">Limits and behavior</h2>

<ul>
  <li>One issue per submission — no comment-on-existing-issue mode</li>
  <li>Title is plain text, truncated with an ellipsis past 255 characters; description is markdown-only</li>
  <li>
    An empty title falls back to <code>New submission to &lt;form name&gt;</code>
  </li>
  <li>File upload answers render as the file name followed by its download link, so the file is reachable from the issue</li>
  <li>
    A <a href="/building-forms/repeating-groups">repeating group</a> field inserted with @ renders every entry joined by " · "
  </li>
</ul>

<h2 id="faq">FAQ</h2>

  <p>
    Three Linear OAuth scopes: <code>read</code> (list teams, projects, and labels),
    <code>write</code> (update issue metadata), and <code>issues:create</code> (create issues). The connection uses <code>actor=user</code>,
    so issues are attributed to you, not a bot.
  </p>

  <p>
    Yes. Open the integration detail sheet and change either field. Switching teams resets the project since projects are team-specific.
  </p>

  <p>Yes. Authorize different Linear accounts to add multiple credentials. Each form integration picks which one to use.</p>

  <p>
    Yes. Linear connections are workspace-scoped. Any workspace member can use any connected Linear account when setting up an integration.
  </p>

  <p>
    The integration auto-pauses and an email goes to the person who set it up. A revoked token, a lost permission, or a deleted team does
    not wait for five failures — it stops the integration immediately. Either way, fix the cause and press Resume.
  </p>

<h2 id="next-steps">Next steps</h2>
<div class="not-prose grid gap-3 sm:grid-cols-2">
  - [GitHub Issues](/integrations/github) — Turn submissions into GitHub issues
  - [Health and monitoring](/integrations/health-monitoring) — Track integration errors and token refresh status
</div>