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, labels, 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, labels, 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 / labels / 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.
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.

Multiple Templates

You can configure multiple team templates within a single Linear integration. Each template has its own team, open/close states, optional project, severity threshold, and auto-create setting. This allows different Linear teams to receive issues with different configurations from the same Guard integration. 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 correctly.

Issue Lifecycle

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

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. These are available under the More Actions dropdown on any vulnerability.

Create New Issue — Manually creates a Linear issue for the vulnerability under the team of your choosing. This is available whether or not auto-create is enabled.
Associate Existing Issue — Links an existing Linear issue to the vulnerability by providing the issue identifier.
Disconnect — Unlinks a Linear issue from the vulnerability without deleting the issue in Linear.

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.