Skip to main content
Connect DevHelm to Linear to open an issue automatically whenever an incident is detected. DevHelm calls Linear’s GraphQL API (issueCreate), so every incident lands in your team’s backlog with the failure context and a link back to DevHelm.

​
Setup

1

Get your Linear API key and team ID

  1. In Linear, go to Settings → Security & access → Personal API keys
  2. Click Create API key, name it (e.g. “DevHelm”), and copy it immediately — Linear shows it only once
  3. Find the team ID (a UUID) for the team where issues should be created. The fastest way is Cmd/Ctrl + K → Copy model UUID while viewing the team. You can also query the API:
query Teams {
  teams {
    nodes {
      id
      name
    }
  }
}
  1. (Optional) To attach a label, grab its label ID the same way (Copy model UUID on the label). The label must belong to the team you selected above.
2

Create the alert channel in DevHelm

devhelm alert-channels create \
  --name "Linear Issues" \
  --type linear \
  --config '{"channelType":"linear","apiKey":"lin_api_xxxxxxxx","teamId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}'
3

Test the channel

devhelm alert-channels test <channel-id>

​
Configuration

FieldDescriptionRequired
apiKeyLinear personal API key (sent as the raw Authorization header — no Bearer prefix)Yes
teamIdUUID of the Linear team where issues are createdYes
labelIdLabel ID attached to created issues; must belong to the selected teamNo

​
What gets created

Linear is a fire-and-forget channel: DevHelm creates a new issue for each incident event routed to it — it does not transition or reopen an existing issue. Each issue includes:
  • Title — incident severity and the affected monitor name
  • Body — failure reason, last status code, check duration, and affected regions
  • A View in DevHelm link back to the incident

​
Troubleshooting

  1. A personal API key inherits the permissions of the user who created it — confirm that user can create issues in the target team.
  2. Run devhelm alert-channels test <id> to surface the exact Linear error.
  3. Regenerate the key if it was revoked or scoped too narrowly.
teamId must be the team’s UUID (e.g. a1b2c3d4-...), not its short key like ENG. Use Cmd/Ctrl + K → Copy model UUID, or the teams GraphQL query above, to get the correct value.
A label can only be attached to issues in the team that owns it. Make sure labelId belongs to the same team as teamId — cross-team label IDs are rejected.