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

# Jira

> Open a Jira issue per incident and transition it when the incident resolves.

Observer opens a Jira issue when an incident is published and transitions it
when the incident resolves. One Observer incident maps to one Jira issue.

## Set up

<Steps>
  <Step title="Create an API token">
    At id.atlassian.com, open **Security**, then **API tokens**, and create a token
    for the account that should own the issues. Note the account email and the
    token.
  </Step>

  <Step title="Add the integration in Observer">
    In the console, open **Alerts**, choose **Add alert**, pick **Jira**, and enter:

    * **Site**: your Atlassian Cloud host, for example `your-org.atlassian.net`.
    * **Account email** and **API token**: the credentials from the previous step.
    * **Project key**: the project issues are created in, for example `OPS`.
    * **Issue type**: defaults to `Task`.
    * **Resolve transition**: the workflow transition used when the incident
      resolves. Defaults to `Done`.

    Choose org-wide or a single page, then save.
  </Step>

  <Step title="Test it">
    Use **Send test** from the row's actions menu. A test issue should appear in the project. Delete or
    close it when you are done.
  </Step>
</Steps>

## Required permissions

A Jira API token uses Basic authentication and inherits the permissions of the
account that created it. There are no OAuth scopes to grant. In the target
project, that account needs:

| Permission | Used for |
| - | - |
| Browse Projects | Finding the incident's existing issue by label |
| Create Issues | Opening the issue when an incident is published |
| Add Comments | Posting incident updates onto the issue |
| Transition Issues | Moving the issue to the resolve transition |

If the account cannot perform one of these, the matching step is reported as a
failure with the Jira error in the delivery result.

## Lifecycle mapping

| Observer event | Jira action |
| - | - |
| Incident published | Create an issue, labeled with the incident |
| Incident update posted | Comment on the issue |
| Incident resolved | Transition the issue to the resolve transition |

Correlation is by label. Each issue carries a label derived from the Observer
incident id (`observer-incident-<id>`). Updates comment on that issue and the
resolve transitions it, so the lifecycle produces one issue, not several.

<Info>
  **The resolve transition must exist**

  The resolve transition is matched by name (case-insensitive) against the
  transitions available on the issue. If your workflow uses a name other than
  `Done` (for example `Resolve` or `Close`), set it in the integration. If no
  matching transition is available from the issue's current status, the resolve
  is reported as a failure with `transition_not_found`.
</Info>

## Troubleshooting

* **No issue is created**: confirm the project key exists and the account can
  create issues of the configured type in that project. Jira returns a 4xx with
  the reason, which Observer surfaces in the delivery result.
* **Authentication failures**: the token must belong to the account email you
  entered. Re-create the token if unsure.
* **Resolve does nothing**: check the resolve transition name against the
  issue's workflow.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.