# Create Jira Issues from Alerts

> Setup Jira integration to automatically create issues from Last9 alerts.

Source: https://last9.io/docs/jira-integration/

## Getting started

Last9 can automatically create Jira issues when alerts are triggered. This document provides step-by-step instructions on how to set up Jira integration with Last9.

:::tip
Last9 automatically detects Jira webhook URLs and creates issues using the Atlassian Document Format (ADF) for rich, structured issue descriptions with code blocks, links, and formatted text.
:::

## Prerequisites

- A Jira Cloud or Jira Data Center instance
- API token or credentials with permission to create issues
- Project key where issues should be created

## Setting up Jira API Access

### For Jira Cloud:

1. Log in to your Atlassian account at [id.atlassian.com](https://id.atlassian.com)

2. Go to **Security** > **API tokens**

3. Click **Create API token**

4. Give it a descriptive label (e.g., "Last9 Integration")

5. Copy the generated token

6. Your webhook URL will be:

   ```
   https://your-domain.atlassian.net/rest/api/3/issue
   ```

7. For authentication, you'll need to base64 encode `email:api_token`:
   ```
   echo -n "your-email@example.com:your-api-token" | base64
   ```

### For Jira Data Center:

1. Generate a Personal Access Token (PAT) from your Jira profile

2. Your webhook URL will be:
   ```
   https://your-jira-server.com/rest/api/2/issue
   ```

## Setting up a notification channel in Last9

1. In [Notification Channels](https://app.last9.io/alerting/notification-channels/), click **Add** to create a new channel

   ![Notification channels list](../../../../../assets/content/docs/alerting/overviews/notification-channels-overview/notification-channel-1.png)

2. Provide the following details:

   - **Channel Name**: A descriptive name to easily identify the channel (e.g., "Jira Production Alerts")
   - **Channel**: Select **Webhook** from the dropdown
   - **Webhook URL**: Enter your Jira API endpoint:
     ```
     https://your-domain.atlassian.net/rest/api/3/issue
     ```
   - **Headers**: Add the following headers:

     | Key                                  | Value                                | Required |
     | ------------------------------------ | ------------------------------------ | -------- |
     | `Authorization`                      | `Basic <base64-encoded-credentials>` | Yes      |
     | `Content-Type`                       | `application/json`                   | Yes      |
     | `JIRA_PROJECT_NAME_KEY`              | Your project key (e.g., `ALERTS`)    | Yes      |
     | `JIRA_PRIORITY_ENABLED`              | `true` to enable priority mapping    | Optional |
     | `JIRA_PROJECT_RESOLUTION_STATUS_KEY` | Transition ID for resolved status    | Optional |

   - **Send Resolved**: Enable if you want resolution comments added to issues

   ![Add webhook channel](../../../../../assets/content/docs/alerting/overviews/notification-channels-overview/webhook-channel-config.png)

3. Click **Save** to enable the channel

:::warning
The `JIRA_PROJECT_NAME_KEY` header is required. Without it, Last9 cannot create issues in your Jira project.
:::

## Assigning a notification channel to an alert group

1. Navigate to your Alert Group in [Alerting](https://app.last9.io/alerting/)

2. Click on the notification channel icon to configure notifications

3. Select your Jira channel from the dropdown

## Jira Issue Format

Last9 creates Jira issues with the following structure:

| Field       | Description                                                 |
| ----------- | ----------------------------------------------------------- |
| Project     | Set via `JIRA_PROJECT_NAME_KEY` header                      |
| Summary     | Alert summary (max 255 characters)                          |
| Issue Type  | Task                                                        |
| Description | ADF-formatted description with full alert details           |
| Labels      | `last9-automated-alert` + deduplication key                 |
| Priority    | Mapped from severity (if `JIRA_PRIORITY_ENABLED` is `true`) |

### Priority Mapping

When `JIRA_PRIORITY_ENABLED` is set to `true`:

| Last9 Severity | Jira Priority |
| -------------- | ------------- |
| Breach         | Highest       |
| Threat         | High          |

### Issue Description

The issue description is formatted using Atlassian Document Format (ADF) and includes:

- **Main Information**: Top-level alert fields (summary, severity, timestamp)
- **Custom Details**: All custom details as labeled fields
- **URLs**: Clickable links to the Last9 dashboard
- **Raw Data**: Full JSON payload in a code block for debugging

### Labels

Each issue is automatically labeled with:

- `last9-automated-alert` - For easy filtering
- Deduplication key - For tracking related alerts

### Deduplication

Last9 only creates Jira issues for **first-time alerts**. Repeated triggers of the same alert will not create duplicate issues. This is controlled by checking the repeat count - if an alert has been triggered more than once, a new issue is not created.

### Resolution Handling

When **Send Resolved** is enabled:

1. Last9 finds the existing Jira issue using the deduplication key label
2. Adds a resolution comment with the timestamp
3. Optionally transitions the issue to a resolved status (if `JIRA_PROJECT_RESOLUTION_STATUS_KEY` is configured)

---

## Configuration Examples

### Basic Configuration (Issues Only)

```
Headers:
  Authorization: Basic dXNlckBleGFtcGxlLmNvbTpteS1hcGktdG9rZW4=
  Content-Type: application/json
  JIRA_PROJECT_NAME_KEY: ALERTS
```

### With Priority Mapping

```
Headers:
  Authorization: Basic dXNlckBleGFtcGxlLmNvbTpteS1hcGktdG9rZW4=
  Content-Type: application/json
  JIRA_PROJECT_NAME_KEY: ALERTS
  JIRA_PRIORITY_ENABLED: true
```

### With Auto-Resolution

```
Headers:
  Authorization: Basic dXNlckBleGFtcGxlLmNvbTpteS1hcGktdG9rZW4=
  Content-Type: application/json
  JIRA_PROJECT_NAME_KEY: ALERTS
  JIRA_PRIORITY_ENABLED: true
  JIRA_PROJECT_RESOLUTION_STATUS_KEY: 31
```

:::note
To find the transition ID for your resolved status, use the Jira API:

```
GET /rest/api/2/issue/{issueKey}/transitions
```

:::

---

## Using Terraform

You can also create the Jira notification channel using the [Last9 Terraform Provider](/docs/terraform-provider/):

```hcl
resource "last9_notification_channel" "jira" {
  name          = "jira-production-alerts"
  type          = "webhook"
  destination   = "https://your-domain.atlassian.net/rest/api/3/issue"
  send_resolved = true

  headers = {
    Authorization             = "Basic <base64-encoded-credentials>"
    Content-Type              = "application/json"
    JIRA_PROJECT_NAME_KEY     = "ALERTS"
    JIRA_PRIORITY_ENABLED     = "true"
  }
}
```

---

## Troubleshooting

### Issues not being created

1. Verify the webhook URL is correct and contains `atlassian.net` (Cloud) or your Jira server URL
2. Check that the API token/credentials are valid
3. Ensure the `JIRA_PROJECT_NAME_KEY` header is set correctly
4. Verify the project exists and your credentials have permission to create issues
5. Check Jira's issue type settings - "Task" must be available in the project

### Authentication errors (401)

1. Verify your API token hasn't expired
2. Check that the base64-encoded credentials are correct
3. Ensure you're using the correct format: `email:api_token` for Cloud

### Project not found errors

1. Verify the project key is correct (case-sensitive)
2. Ensure your credentials have access to the project

### Issues not being resolved

1. Ensure **Send Resolved** is enabled
2. Check that the original issue still exists and has the correct label
3. Verify the `JIRA_PROJECT_RESOLUTION_STATUS_KEY` transition ID is valid

### Alternative header name

Last9 also accepts `project_key` (lowercase) as an alternative to `JIRA_PROJECT_NAME_KEY`.

Please get in touch with us on [Discord](https://discord.com/invite/Q3p2EEucx9) or [Email](mailto:support@last9.io) if you have any questions.