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

# Jira

> Hold a pull request to the Jira ticket it links: setup, what is read, what is stored, and how to disconnect.

When a pull request links a Jira ticket, CodeWarden reads the ticket and reports code that does something **different** from what the ticket states. These findings use the category `acceptance`.

It never reports that something the ticket asks for is missing. A review sees part of a change, never all of it, and the rest of the ticket may be done in another pull request.

## Requirements

* **Jira Cloud** (`*.atlassian.net`). Jira Server and Jira Data Center are not supported.
* An [owner](/console/organizations-and-roles) of the organization in the CodeWarden console, to connect it.
* Someone who can merge to the base branch, to list the allowed projects in `.codewarden.yml`.

## Set it up

<Steps>
  <Step title="Connect Jira in the console">
    On the console's home page, open the installation and, under **Integrations**, click **Connect Jira**. Atlassian asks you to grant CodeWarden read access. If your Atlassian account can see several Jira sites, the console then asks **Which site?**; pick one.

    One installation has one Jira site. Connecting again replaces the previous grant, which is also how a broken connection is repaired.
  </Step>

  <Step title="Allow the projects in .codewarden.yml">
    Add the Jira project keys a pull request may link tickets from, and merge it into the base branch:

    ```yaml .codewarden.yml theme={null}
    jira:
      projects: ["PROJ"]
      public_repositories: false
    ```

    Without this list no ticket is read, even with Jira connected. On a public repository, nothing is read unless `public_repositories` is `true`.
  </Step>

  <Step title="Link the ticket in the pull request">
    Put the ticket's URL in the pull request's title or description:

    ```text theme={null}
    Closes https://acme.atlassian.net/browse/PROJ-123
    ```

    A bare key such as `PROJ-123` is not matched; only a full URL is. The review's summary ends with `Checked against PROJ-123.` when the ticket was read.
  </Step>
</Steps>

## When a ticket is read

All of these must hold. Otherwise the review runs without the ticket, and the console shows why on the review's page.

1. The URL is in the pull request's title or description, in the form `https://<site>/browse/<KEY-123>`.
2. The ticket's project is listed in `jira.projects` on the base branch.
3. The URL's site is the site connected to the installation. A link to any other site is never read.
4. The repository is private, or `jira.public_repositories` is `true`.
5. The connection is working.

One ticket is read per review: the first linked URL that passes these checks. A ticket that cannot be read (not found, no permission, or too slow) never fails the review and never marks the connection as broken.

The URL in a pull request is written by whoever opened it, which is why it decides nothing on its own: the project list in your repository is what you trust.

## What is read

The ticket's **summary, description, type, status and project**, in one read-only request per review. The text is shown to the model as data to check the code against, never as instructions.

CodeWarden asks Atlassian only for read scopes (`read:jira-work` and `offline_access`). It never creates, edits or comments on Jira issues.

## What is stored

* **The connection's tokens**, encrypted at rest, because reviews use them when nobody is signed in. They are renewed automatically, and a connection idle for 30 days is renewed in the background so Atlassian does not expire it.
* **Which ticket was used**: its key, site, URL, and the outcome of the read, on the review's record.
* **Not the ticket's text.** The model reads the title and description, but the copy of the prompt CodeWarden keeps has them removed.

## Connection states

The installation's **Integrations** box in the console shows one of:

| State | Meaning |
| - | - |
| not connected | No grant. **Connect Jira**. |
| access granted, Which site? | The grant covers several sites. Pick one. |
| connected | Working. Shows the site, the date it was connected, and when it last worked. Owners can **Test connection**. |
| needs reconnecting | Atlassian refused the grant: it was revoked, expired after 90 days of inactivity, or spent. Click **Reconnect Jira**. |

## Disconnect and revoke

* **In the console:** an owner clicks **Disconnect** in the installation's Jira box. The stored tokens are deleted.
* **In Atlassian:** the person who connected it can remove CodeWarden at [id.atlassian.com](https://id.atlassian.com) → **Connected apps**, or a site administrator can remove the app from the site.

Connecting, choosing a site, disconnecting and a connection breaking all appear in the organization's [activity log](/console/activity-log).


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