Linear Integration with DefectDojo

Linear Integration with DefectDojo

Linear is a commercial issue tracking and project planning tool for software teams. Work is organized into teams, each with its own issues, workflow states, and cycles, and every issue carries a numeric priority from Urgent to Low. Linear exposes its data through a GraphQL API, which DefectDojo Pro uses to create and update issues.

Linear Integration with DefectDojo

Our engineers plan their week in Linear, so a security finding that only exists in DefectDojo is a finding they will not see. The Linear Downstream Connector in DefectDojo Pro closes that gap by pushing Findings out as Linear Issues in the team that owns the code. Severity becomes Linear priority, the Finding's status drives the issue's workflow state, and DefectDojo keeps a link to each issue so we can see from the security side which findings are already being worked. Triage, deduplication, and SLA tracking still happen in DefectDojo. Linear is where the fix gets scheduled.

Why Linear Matters

Remediation happens where engineers already take their work from. For teams that use Linear, that is the issue list, not a security dashboard.

• Issues in a team's backlog get scheduled into cycles alongside feature work, which is how security fixes actually get done.
• Linear's priority field is visible on every list and board, so a mapped Critical shows up as Urgent without anyone retyping it.
• Workflow states are defined per team, so security tickets follow the same Todo, In Progress, and Done flow as everything else.
• Without an integration, someone on the security team copies findings into Linear by hand, and the two systems drift apart as soon as either side changes.

Advantages of This Integration

What we get from pushing findings through DefectDojo instead of filing Linear issues manually:

• Only triaged work reaches engineers. Findings are deduplicated and reviewed in DefectDojo first, so Linear receives one issue per real problem rather than one per scanner hit.
• Severity translates automatically. The connector maps each DefectDojo severity to a Linear priority, using defaults that keep Critical as Urgent and High as High.
• Status stays in step. Active and closed Findings map to Linear Workflow State IDs you choose, and a Finding that is deleted in DefectDojo moves its issue to the closed state.
• Automatic or manual pushes. Each Asset or Engagement assignment can push only on demand, create issues for new Findings automatically, update linked issues when Findings change, or both.
• Push filters keep volume sane. An assignment can limit automatic creation to a minimum severity and to active Findings only, while updates to already linked issues always go through.
• Traceability on the security side. Every linked Finding shows the integration type, the Linear issue ID, a direct link, and a changelog of when DefectDojo last touched the issue.

How This Integration Works

Downstream Connectors are a DefectDojo Pro feature, available on both Cloud and On-Premise instances with nothing to enable. Community Edition's built-in issue tracking integration supports Jira only, so pushing to Linear requires DefectDojo Pro.

A Downstream Connector has three layers: an Integration Instance (the connection), one or more Issue Tracker Mappings (where issues go and how fields map), and Issue Tracker Assignments (which Assets or Engagements use a mapping). Open Connect > Downstream in the Pro UI and choose Linear.

1. Create the Integration Instance.

• Label: a name to identify this integration.
• Location: https://api.linear.app/graphql.
• API Key: a Linear personal API key, generated in Linear under Settings, then Security & access, then API. DefectDojo sends it to Linear's GraphQL API in the Authorization header.

2. Create an Issue Tracker Mapping. Set the Team (Group) ID to the Linear team that should receive issues. You can find team IDs by running a GraphQL query for teams (requesting each node's id, name, and key) against Linear's API with your key.

3. Map severity to priority. The Severity Field Name is Priority. Linear uses 1 for Urgent through 4 for Low. The documented mapping is Critical to 1, High to 2, Medium to 3, and both Low and Info to 4.

4. Map status to workflow states. The Status Field Name is Workflow State ID. Workflow State IDs are unique to each workspace, so there are no defaults. Query workflowStates through the GraphQL API (requesting id, name, type, and team key) to list them. Set Active Mapping to a started or unstarted state such as Todo or In Progress, and Closed Mapping to a completed state such as Done.

5. Assign Assets or Engagements. Create an Issue Tracker Assignment for each Asset or Engagement that should push to this team, and pick one of the four push behaviors along with any push filters.

Data Granularity: What Gets Sent

Errors from failed pushes, such as a revoked key or an invalid state ID, are listed per mapping on the All Issue Tracker Mappings & Assignments page, and in the instance-wide Diagnostics view.

Use Cases

Routing by team: A company with separate Linear teams for web, mobile, and platform creates one Issue Tracker Mapping per team and assigns each to the matching DefectDojo Asset. Findings from that Asset's scanners land in the right backlog without a triage handoff.

Pushing only what matters: An assignment set to automatically link new Findings, with a Minimum Severity of High and Active findings only, keeps Linear focused on urgent work. Lower findings can still be pushed one at a time with Push to Integrator when someone decides they belong in a sprint.

Closing the loop on fixes: When a reimport shows a vulnerability is gone and the Finding is mitigated, an assignment that updates existing links moves the Linear issue to the closed state, so engineers do not have to close it twice.

Audit trail: Each linked Finding records when its Linear issue was created and last updated by DefectDojo, which helps answer how quickly a Critical reached the owning team.

Operational Tips

• Use a personal API key from a dedicated service user, so issues created by DefectDojo are easy to tell apart from issues people filed.
• Pick Workflow State IDs that belong to the team named by the Team (Group) ID. The workflowStates query returns each state's team key, which makes the match easy to check.
• Low and Info both map to priority 4 by default. If Info findings should never reach Linear, set the assignment's Minimum Severity instead of relying on priority.
• Push filters apply only to automatic creation. Status updates for issues that already exist are always sent, which is what keeps closures in sync.
• Start with "Only Explicitly Publish Changes to Target" while you test mappings, then switch to an automatic option once a few manual pushes look right.
• Check the Total Errors column on the mappings page after any change to keys or states.