# Jira Cloud

Connecting Jira Cloud lets EvoHub open a Jira issue for each incident and keep it in step with the incident. Your team keeps working in EvoHub; the issue is where the rest of the company follows along.

Jira is free: issues, comments and transitions are not metered.

## What the Jira integration does

- **Opens one issue per incident.** By default every new incident opens an issue in the project you choose. You can also open issues for alerts at or above a severity, or turn automatic creation off and use the button instead.
- **Fills the issue in.** The summary is `INC-<number>: <title>` (for an alert, its title). The description has the incident summary, its severity and an **Open in EvoHub** link. The Jira priority follows the severity, using the mapping you choose, and your labels are added.
- **Posts updates as comments** if you turn that on: notes added to the incident timeline, and when the incident is identified and resolved. For alerts: acknowledged, taken over, reassigned and resolved.
- **Moves the issue when the incident is resolved**, to the status you choose — for example **Done**.
- **Shows the issue on the incident page.** The issue key appears at the top of the incident (or alert) and opens the issue in Jira.

Only one issue is ever opened for an incident, even when the automatic creation and the button happen at the same time.

## Before you start

You need:

- A **Jira Cloud** site (an address ending in `.atlassian.net`). Jira Data Center and Server are not supported.
- An Atlassian account for EvoHub to act as. Issues and comments appear under this account, so many teams create a dedicated one, such as `oncall-bot@your-company.com`. It needs these permissions in the project: **Browse projects**, **Create issues**, **Add comments** and **Transition issues**.
- An **API token** for that account. Create one at [id.atlassian.com → Security → API tokens](https://id.atlassian.com/manage-profile/security/api-tokens).

## Connect Jira

:::steps
### Open the Jira settings
Go to **On-Call → Integrations** and click **Jira Cloud**.
### Enter the connection
Enter your **Jira site** (`https://your-team.atlassian.net`), the account's **email** and the **API token**, then click **Connect**. EvoHub checks them with Jira before saving.
### Choose the project and issue type
Under **Issues**, pick the **Project** and the **Issue type** (for example *Task* or *Incident*). Sub-task types cannot be used.
### Decide when issues are created and what they say
Choose whether **every new incident** opens an issue, which **alerts** do (**Never** by default), a Jira **priority** for each severity, any **labels**, whether to **post comments**, and the status to **move the issue to when resolved**. Click **Save**.
:::

EvoHub stores the API token encrypted and never shows it again. To use a new token, click **Replace token**. Connecting a different Jira site clears the project settings, because they belong to the old site.

Connecting Jira and changing its settings need the On-Call settings permission. Anyone who can see integrations can see whether Jira is connected.

## Create an issue by hand

When automatic creation is off — or for an incident or alert that did not qualify — open it and click **Create Jira issue** at the top of the page. Clicking it again, or while an issue is being created, does not open a second one.

Creating an issue from an incident needs permission to edit incidents; from an alert, permission to respond to alerts.

If Jira refused the issue (for example because the account cannot create issues in the project, or a priority is not allowed there), the button reads **Retry Jira issue**. Hover over it to see Jira's reason, fix the setting, and click it again.

## When the incident is resolved

If you chose a status under **When resolved, move the issue to**, EvoHub moves the issue there when the incident (or alert) is resolved. It uses the transition in your Jira workflow that leads to that status. If the issue is already in that status, nothing changes. If your workflow has no way to that status from where the issue is, the issue is left as it is.

## Good to know

- Each issue also carries a label like `evohub-incident-<id>`. EvoHub uses it to find the issue again if a request to Jira was interrupted, so please leave it on the issue.
- Changes made in Jira do not come back to EvoHub yet: closing the issue in Jira does not resolve the incident.
- Incidents recorded after they ended do not open issues automatically.

## Disconnect

On the Jira page, click **Disconnect** and confirm. EvoHub forgets the API token and stops creating and updating issues. Issues already created stay linked to their incidents, so their keys still show on the incident pages.

## Related

- [Alerts and incidents](https://docs-dev.evohub.io/alerts-and-incidents.md)
- [Integrations overview](https://docs-dev.evohub.io/integrations-overview.md)
- [Slack](https://docs-dev.evohub.io/slack.md)