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.
- Open Integrations. Under Issue tracking, choose Connect next to Linear.
- Fill in the two fields and save.
| Field | API name | What to enter |
|---|---|---|
| API key | apiKey | A Linear API key. Issues are created as the account the key belongs to. |
| Team ID | teamId | The 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:
| Part | Content |
|---|---|
| Title | The severity in square brackets and the finding's title, for example [HIGH] SQL injection in order lookup. |
| Priority | Critical is urgent, high is high, medium is medium, low is low. An info finding gets no priority. |
| Description | A 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
400with the codetracker_rejectedand Linear's reason. - If Linear is not connected the answer is
400with the codenot_connected. - Filing is recorded in the audit log as
finding.issue_createdwith the detaillinear. Connecting and disconnecting are recorded asintegration.connectedandintegration.disconnected.
#What it does not do
| Linear | Jira | |
|---|---|---|
| File a finding as an issue | Yes | Yes |
| Comment on the issue when the finding changes state | No | Yes |
| Move the issue when the finding is closed or reopened | No | Yes |
| Close or reopen the finding when the issue is closed or reopened | No | Yes |
| Labels on the created issue | No | Yes |
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