> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devhelm.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Linear

> Create Linear issues automatically when DevHelm detects an incident

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

<Steps>
  <Step title="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:

    ```graphql theme={null}
    query Teams {
      teams {
        nodes {
          id
          name
        }
      }
    }
    ```

    4. *(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.
  </Step>

  <Step title="Create the alert channel in DevHelm">
    <CodeGroup>
      ```bash CLI theme={null}
      devhelm alert-channels create \
        --name "Linear Issues" \
        --type linear \
        --config '{"channelType":"linear","apiKey":"lin_api_xxxxxxxx","teamId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}'
      ```

      ```yaml devhelm.yml theme={null}
      alertChannels:
        - name: Linear Issues
          config:
            channelType: linear
            apiKey: ${LINEAR_API_KEY}
            teamId: ${LINEAR_TEAM_ID}
            labelId: ${LINEAR_LABEL_ID} # optional
      ```
    </CodeGroup>
  </Step>

  <Step title="Test the channel">
    ```bash theme={null}
    devhelm alert-channels test <channel-id>
    ```
  </Step>
</Steps>

## Configuration

| Field     | Description                                                                           | Required |
| --------- | ------------------------------------------------------------------------------------- | -------- |
| `apiKey`  | Linear personal API key (sent as the raw `Authorization` header — no `Bearer` prefix) | Yes      |
| `teamId`  | UUID of the Linear team where issues are created                                      | Yes      |
| `labelId` | Label ID attached to created issues; must belong to the selected team                 | No       |

## 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

<AccordionGroup>
  <Accordion title="Issues aren't being created">
    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.
  </Accordion>

  <Accordion title="Linear rejects the team ID">
    `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.
  </Accordion>

  <Accordion title="Label isn't applied">
    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.
  </Accordion>
</AccordionGroup>