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

# Jira

> Automatically create Jira issues in your project when DevHelm incidents occur

Connect DevHelm to Jira to open an issue in your project on every incident event. DevHelm uses the [Jira Cloud REST API v3](https://developer.atlassian.com/cloud/jira/platform/rest/v3/) with Basic authentication (your Atlassian account email plus an API token), creating one issue per event in the project and issue type you choose.

## Setup

<Steps>
  <Step title="Create an Atlassian API token">
    1. Go to [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
    2. Click **Create API token**, give it a descriptive label, and choose an expiry
    3. Copy the token immediately — Atlassian shows it only once

    Note the **email** of the Atlassian account that created the token; you'll need both for authentication.
  </Step>

  <Step title="Find your domain, project key, and issue type">
    * **Domain** — your Atlassian site, e.g. `yourteam.atlassian.net` (just the host, no `https://`)
    * **Project key** — the uppercase prefix on issue IDs; if your issues are `OPS-123`, the key is `OPS`
    * **Issue type** — the name of an existing type in that project (e.g. `Bug`, `Task`, `Incident`). Defaults to `Bug` if omitted. The name is case-sensitive and must already exist in the project.
  </Step>

  <Step title="Create the alert channel in DevHelm">
    <CodeGroup>
      ```bash CLI theme={null}
      devhelm alert-channels create \
        --name "Jira Issues" \
        --type jira \
        --config '{"channelType":"jira","domain":"yourteam.atlassian.net","email":"you@company.com","apiToken":"your-atlassian-api-token","projectKey":"OPS","issueType":"Bug"}'
      ```

      ```yaml devhelm.yml theme={null}
      alertChannels:
        - name: Jira Issues
          config:
            channelType: jira
            domain: yourteam.atlassian.net
            email: you@company.com
            apiToken: ${JIRA_API_TOKEN}
            projectKey: OPS
            issueType: Bug
      ```
    </CodeGroup>
  </Step>

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

## Configuration

| Field        | Description                                                              | Required |
| ------------ | ------------------------------------------------------------------------ | -------- |
| `domain`     | Atlassian instance domain, e.g. `yourteam.atlassian.net` (no `https://`) | Yes      |
| `email`      | Atlassian account email associated with the API token                    | Yes      |
| `apiToken`   | Atlassian API token used for Basic auth                                  | Yes      |
| `projectKey` | Project key where issues are created, e.g. `OPS`                         | Yes      |
| `issueType`  | Issue type name; defaults to `Bug` (case-sensitive, must exist)          | No       |

## Issue format

DevHelm creates one issue per incident event (fire-and-forget — it does not reopen or transition existing issues). The summary leads with the severity and monitor name, and the description includes the monitor URL, failure reason, latest status code, duration, and a link back to the incident in DevHelm.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication fails (401)">
    1. Use the **API token**, not your account password
    2. Make sure `email` is the exact Atlassian account that created the token
    3. If the token expired, generate a new one and update the channel
  </Accordion>

  <Accordion title="Project or issue type not found (404)">
    1. Confirm `domain` is just the host (`yourteam.atlassian.net`) with no `https://` prefix or trailing path
    2. Verify the `projectKey` exists and is the uppercase prefix from issue IDs (e.g. `OPS` from `OPS-123`)
    3. Check `issueType` matches an existing type name in that project exactly — names are case-sensitive
  </Accordion>

  <Accordion title="Issues aren't being created despite a successful auth">
    The account behind the token needs **Create issue** permission in the target project. Confirm the user's project role grants it, then run `devhelm alert-channels test <id>`.
  </Accordion>
</AccordionGroup>