Linear

Guard's Linear integration enables automatic and manual creation of vulnerability issues, bidirectional status synchronization, and configurable open/close state mapping. This guide walks you through the setup process and covers the full set of features available once the integration is active.

Prerequisites

Before beginning the integration setup, ensure you have:

Access to create personal API keys in your Linear workspace
A designated Linear team (or teams) for security vulnerabilities

Getting Started

To begin setting up your Linear integration, log into Guard and click Integrations in the left sidebar. Click Add Integration, select the IT Service Management category, and choose the Linear tile.

Linear Configuration

Linear configuration is a two-step process: authentication and team configuration. Linear's data model is team-scoped — workflow states and (optionally) projects are all selected relative to the team you pick, which keeps state IDs consistent with the team that owns each issue.

Step 1: Authentication

Before entering credentials in Guard, you will need to create a personal API key in Linear.

API Key — Create a personal API key in your Linear account. The user who generates the key must be a workspace member with access to the target team(s) and the ability to create and update issues. Linear API keys inherit the full permissions of the issuing user; there are no granular scopes like Jira.

To create the key, go to your Linear account settings at https://linear.app/settings/account/security, click New API key, and give it a meaningful label such as "Guard Integration." Copy the key immediately — it begins with lin_api_ and Linear will not show it again after the dialog closes.

Paste the key into Guard's authentication dialog and click Connect to proceed.

Step 2: Team Configuration

Once authenticated, configure how Guard sends issues to Linear. Guard fetches the live list of teams, workflow states, and projects from Linear so every dropdown matches your real workspace.

Display Name — A display name for this integration (e.g., "Security Team Linear").
Team — Select from the Linear teams visible to your API key. Linear issues are owned by exactly one team, and the workflow states and projects available below are scoped to your selection.
Open State — The workflow state new issues will land in. Guard pre-selects the first state whose type is unstarted (typically "Todo"). This is also the state Guard transitions issues back to when a previously closed vulnerability is reopened. Guard works seamlessly with Linear's Triage feature: if your team has Triage enabled, new issues briefly pass through Triage and are automatically moved to your configured Open State within the same request — no manual triage acceptance is required.
Close State — The workflow state Guard will transition issues to when the linked vulnerability is closed in Guard. Guard pre-selects the first state whose type is completed (typically "Done"). State matching is done by the universal state type (triage / backlog / unstarted / started / completed / canceled), not by the display name, so renamed states still resolve correctly across the bidirectional sync.
Project (optional) — Attach new issues to a Linear project. Leave on — No project — to create issues at the team level.
Minimum Severity — The severity threshold for automatic issue creation. Options are Critical, High, Medium, Low, and Informational. Only vulnerabilities at or above this level will trigger automatic issues.
Auto-Create Issues — When enabled, Guard automatically creates a Linear issue whenever a new vulnerability meeting the severity threshold is discovered.

Click Connect to complete the setup. Changing the team later resets the Open State, Close State, and Project selections so stale state IDs from a different team cannot slip into the saved configuration.

Routing to Multiple Teams

Guard supports two ways to send the same vulnerability to more than one Linear team:

Multiple templates within one integration — within a single Linear integration (one API key), you can configure separate templates per team using the Add Project button on the configuration screen. Each template has its own team, open/close states, optional project, severity threshold, and auto-create setting. This is the simplest setup when you want one set of Linear credentials to file issues into several teams.
Multiple Linear integrations — you can also add the Linear integration more than once (e.g., one per workspace, or one per Linear account). Each integration is its own row on the Integrations page with its own credentials and templates. Use this when separate Linear workspaces or different API keys need to file the same finding.

Both options behave the same way at auto-create time: Guard evaluates every template across every Linear integration on the tenant, and any template whose severity threshold matches the vulnerability and has Auto-Create Issues enabled will create a ticket. This is parallel fan-out — a single Critical-severity vulnerability with two matching templates will produce two Linear issues, one in each configured team. When Guard transitions an issue at close or reopen time, it looks up the correct template by the team the issue actually belongs to, so multi-team configurations route their state changes correctly.

Controlling Which Templates Fire

When you have multiple templates or integrations, you can shape which ones receive each vulnerability without code changes:

Severity thresholds — set different minimum severities per template (e.g., one template only catches Critical, another catches High and above) so each team sees only the findings relevant to them.
Auto-create toggles — turn Auto-Create Issues off on templates that should only be filed manually. Manual creation through the vulnerability drawer's Ticketing button still works.
Manual routing per vulnerability — on any vulnerability drawer, click Ticketing, pick which integration and template to file the issue against, and confirm. This is the only way to file a ticket if every template has Auto-Create off, and it's also useful for one-off routing decisions.

Issue Lifecycle

Once configured, Guard manages the full lifecycle of Linear issues as vulnerability statuses change.

Automatic ticket creation fires when a vulnerability transitions to Demonstrated (Open) from another status — for example, when triage moves a Triaged finding to Demonstrated, or when a remediated finding is re-detected and reopened. Saving the same Demonstrated status onto a vulnerability that's already Demonstrated does not refire auto-create; this prevents a single triage decision from generating duplicate Linear issues. If you disconnect a ticket from a vulnerability and want a fresh one created, briefly transition the vulnerability to a non-Open status and back to Demonstrated, or use the Ticketing button in the vulnerability drawer to create one manually.

Automatic Issue Closing

When a vulnerability status in Guard changes to Remediated, Accepted (Ignored), or Rejected (Deleted), Guard automatically transitions the linked Linear issue to your configured Close State. Guard also adds a Markdown comment to the issue that includes:

The closure reason (Remediated, Auto-Remediated, Rejected, or Accepted)
For rejections, the sub-reason (False Positive, Duplicate, Out of Scope, or Other)
The username of the person who resolved the vulnerability
A link back to the vulnerability in Guard

When a vulnerability is no longer detected by Guard for an extended period and is auto-remediated by the platform, the closure comment carries a different message that notes when the vulnerability was originally discovered and when it was last detected.

Automatic Issue Reopening

When a previously closed vulnerability is redetected by a scan or manually reopened in Guard, Guard transitions the linked Linear issue back to your configured Open State and adds a Markdown comment indicating the reason (Redetected or Manual).

Bidirectional Sync

Guard polls Linear on a schedule and reflects state changes back onto the vulnerability:

Linear-driven close — Moving an issue to a completed- or canceled-typed state in Linear will, on the next sync, mark all-issues-resolved risks as Remediated in Guard.
Linear-driven reopen — Moving an issue back out of a resolved state will, on the next sync, reopen the linked Guard vulnerability if it had been previously remediated.

Because Guard matches resolved state by Linear's universal state type rather than its renameable display name, customizing state names in Linear ("Done" → "Shipped") does not break the sync.

Tag → Label Synchronization

Vulnerability tags in Guard are synced to Linear issue labels at issue creation and on every bidirectional sync poll. Labels are matched to Linear by name on the issue's team; unknown names are ignored. Because Linear's label update is replace-semantic, Guard merges its tag set with any labels already present on the issue rather than overwriting them — labels you add to an issue manually in Linear will survive.

Severity-Change Comments

When the severity of a Guard vulnerability changes, Guard posts a Markdown comment on each linked Linear issue noting the change.

Managing Issues

Guard provides several actions for managing the relationship between vulnerabilities and Linear issues, available from the vulnerability drawer:

Ticketing — opens a routing dialog that lists every Linear integration and template configured on your tenant. Pick the integration and template, click Confirm, and Guard files a new Linear issue against that specific template. Works whether or not auto-create is enabled, and is the right choice when you have multiple templates and want to control which one receives this finding.
Associate Existing Issue (under More Actions) — links an existing Linear issue to the vulnerability by providing the issue identifier. Use this when a Linear ticket was created outside of Guard and you want Guard's bidirectional sync to pick up future state changes on it.
Disconnect (under More Actions) — unlinks a Linear issue from the vulnerability without deleting the issue in Linear. The issue continues to exist in Linear; Guard simply stops tracking it. Auto-create will create a fresh ticket on the next transition into Demonstrated.

Once an issue is linked, the vulnerability drawer in Guard displays the Linear issue identifier (e.g. ENG-123), state, assignee, and a direct link.

What Information Goes Into Linear Issues

When Guard creates a Linear issue, it includes comprehensive vulnerability information to help your team understand and remediate the security issue. Linear renders issue descriptions and comments as Markdown natively, so all formatting is preserved without translation.

Issue Title

The issue title displays the vulnerability title, falling back to the risk name if no title is set.

Issue Description

The description field contains detailed information formatted in Markdown:

Chariot Link: A direct link to view the vulnerability in Chariot.
Severity: The severity level of the vulnerability (Critical, High, Medium, Low, or Informational).
Assets Impacted: A list of all affected assets with their DNS name and asset identifier.
Vulnerability Definition: The complete vulnerability definition including technical details, impact assessment, and remediation recommendations.
Additional Evidence: If evidence has been collected, text-based evidence is included directly in the description.

Project and Initial State

New issues land in the team, project (if configured), and Open State you selected during configuration. Linear labels are populated from the vulnerability's Guard tags. Linear issue identifiers (e.g. ENG-123) are assigned by Linear and shown on the Guard vulnerability drawer as soon as the issue is created.

If you need further assistance, please contact us at support@praetorian.com.