Nullgap.dev Docs

Integrations

Linear

File a finding as a Linear issue, and what the Linear integration does not do.

With Linear connected you can file a finding as an issue in one Linear team. That is all the integration does.

#Connect Linear

You need to be an admin or owner in Nullgap, and a Linear API key that can see the team.

  1. Open Integrations. Under Issue tracking, choose Connect next to Linear.
  2. Fill in the two fields and save.
FieldAPI nameWhat to enter
API keyapiKeyA Linear API key. Issues are created as the account the key belongs to.
Team IDteamIdThe team that receives the issues. The team's id, its short key (such as ENG) or its name are all accepted.

Nullgap asks Linear before it stores anything: it checks that the key is accepted and looks the team up. If the key is refused or no such team is visible to it, nothing is saved and you see the reason, including the team keys the key can see (400 with the code tracker_rejected, or tracker_unreachable when Linear could not be reached).

The key is stored encrypted and is never shown again, in the console or through the API. Replace saves a new one; Disconnect deletes it. One team can be connected per organisation.

Through the API (admin key):

curl -s -X PUT -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"config":{"apiKey":"YOUR_LINEAR_API_KEY","teamId":"ENG"}}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/integrations/linear"

The answer:

{ "kind": "linear", "connected": true, "label": "ENG", "needsReconnect": false }

#File a finding as an issue

Open a finding and choose Create Linear issue. Any member can do this; through the API it needs a key with the write scope:

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tracker":"linear"}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_123/issue"

The answer is the finding, with the issue's address in externalIssueUrl. The finding page then links to the issue.

The issue is created in the connected team with:

PartContent
TitleThe severity in square brackets and the finding's title, for example [HIGH] SQL injection in order lookup.
PriorityCritical is urgent, high is high, medium is medium, low is low. An info finding gets no priority.
DescriptionA one-line statement of the impact, the finding's description, its severity, repository, file and line, weakness ids, the remediation advice, and a link back to the finding in Nullgap (Open in Nullgap).

Things to know:

  • A finding has one issue link. Filing it again returns the finding unchanged and creates nothing, whichever tracker the existing link belongs to. A finding already filed in Jira cannot also be filed in Linear.
  • If Linear refuses the issue, no link is stored and you get 400 with the code tracker_rejected and Linear's reason.
  • If Linear is not connected the answer is 400 with the code not_connected.
  • Filing is recorded in the audit log as finding.issue_created with the detail linear. Connecting and disconnecting are recorded as integration.connected and integration.disconnected.

#What it does not do

LinearJira
File a finding as an issueYesYes
Comment on the issue when the finding changes stateNoYes
Move the issue when the finding is closed or reopenedNoYes
Close or reopen the finding when the issue is closed or reopenedNoYes
Labels on the created issueNoYes

Also:

  • Nothing is sent to Linear after the issue is created. If the finding is later fixed, dismissed or found again, the issue stays as it is.
  • There is no webhook to set up in Linear, and Nullgap does not read anything back from Linear.
  • Nullgap does not create issues on its own. A person or an API call files each one.
  • If the stored key can no longer be read, the Linear row shows Needs reconnecting. Enter the key again.

The routes are listed in the integrations reference.

Nullgap documentation