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

# Jira integrations

<Warning>
  **Git Integration (formerly Qodo Merge)** – AI code review agents for pull requests. This documentation describes the Qodo v1 experience. For the Qodo v2 documentation, click [here.](/code-review)
</Warning>

## Jira Cloud

There are two ways to authenticate with Jira Cloud:

#### **1. Jira app authentication**

The recommended way to authenticate with Jira Cloud is to install the Qodo app in your Jira Cloud instance. This will allow Qodo to access Jira data on your behalf.

**Installation steps:**

<Steps>
  <Step>
    Go to the [Qodo integrations page](https://app.qodo.ai/qodo-merge/integrations).
  </Step>

  <Step>
    Click on **Connect Jira Cloud** to connect the Jira Cloud app.
  </Step>

  <Step>
    Click **Accept**.

    <Frame>
      <img src="https://mintcdn.com/qodo/uIkZ6kAWHm6WXqrW/images/v1/image-107.avif?fit=max&auto=format&n=uIkZ6kAWHm6WXqrW&q=85&s=02f04c6a2528b554803e565683629d6f" alt="" width="613" height="651" data-path="images/v1/image-107.avif" />
    </Frame>
  </Step>

  <Step>
    After installing the app, you will be redirected to the Qodo registration page where you'll see a success message.
  </Step>

  <Step>
    Qodo is now able to fetch Jira ticket context for your PRs.
  </Step>
</Steps>

#### **2. Email/token authentication**

You can create an API token from your Atlassian account:

<Steps>
  <Step>
    Log in to the [API tokens page on Jira](https://id.atlassian.com/manage-profile/security/api-tokens).
  </Step>

  <Step>
    Click **Create API token**.
  </Step>

  <Step>
    Enter a name for your new token and click **Create**.
  </Step>

  <Step>
    Click **Copy to clipboard**.

    <Frame>
      <img src="https://mintcdn.com/qodo/uIkZ6kAWHm6WXqrW/images/v1/image-108.png?fit=max&auto=format&n=uIkZ6kAWHm6WXqrW&q=85&s=83d2eed46ff8ba28a8abeef7db2de088" alt="" width="372" height="296" data-path="images/v1/image-108.png" />
    </Frame>

    Add the following lines in your [configuration file](/v1/configuration/configuration-file):

    ```bash theme={null}
    [jira]
    jira_api_token = "YOUR_API_TOKEN"
    jira_api_email = "YOUR_EMAIL"
    ```
  </Step>
</Steps>

## Jira Data Center/Server

#### **Using basic authentication**

You can use your Jira username and password to authenticate with Jira Data Center/Server.

In your Configuration file/Environment variables/Secrets file, add the following lines:

```bash theme={null}
jira_api_email = "your_username"
jira_api_token = "your_password"
```

#### **Validating Basic authentication via Python script**

If you are facing issues retrieving tickets in Qodo with Basic auth, you can validate the flow using a Python script.

The following steps will help you check if the basic auth is working correctly, and if you can access the Jira ticket details:

<Steps>
  <Step>
    Run:

    ```bash theme={null}
    pip install jira==3.8.0
    ```
  </Step>

  <Step>
    Run the following Python script. Make sure to replace the placeholders with your actual values:

    ```python expandable theme={null}
    from jira import JIRA

    if __name__ == "__main__":
        try:
            # Jira server URL
            server = "https://..."
            # Jira PAT token
            token_auth = "..."
            # Jira ticket code (e.g. "PROJ-123")
            ticket_id = "..."

            print("Initializing JiraServerTicketProvider with JIRA server")
            # Initialize JIRA client
            jira = JIRA(
                server=server,
                token_auth=token_auth,
                timeout=30
            )
            if jira:
                print(f"JIRA client initialized successfully")
            else:
                print("Error initializing JIRA client")

            # Fetch ticket details
            ticket = jira.issue(ticket_id)
            print(f"Ticket title: {ticket.fields.summary}")

        except Exception as e:
            print(f"Error fetching JIRA ticket details: {e}")
    ```
  </Step>
</Steps>

## How to link a PR to a Jira ticket

To integrate with Jira, you can link your PR to a ticket using either of these methods:

#### **Method 1: Description reference**

Include a ticket reference in your PR description, using either the complete URL format `https://<JIRA_ORG>.atlassian.net/browse/ISSUE-123` or the shortened ticket ID `ISSUE-123` (without prefix or suffix for the shortened ID).

#### **Method 2: Branch name detection**

Name your branch with the ticket ID as a prefix (e.g., `ISSUE-123-feature-description` or `ISSUE-123/feature-description`).

#### Jira base URL

For shortened ticket IDs or branch detection (method 2 for JIRA cloud), you must configure the Jira base URL in your [configuration file](/v1/configuration/configuration-file) under the `[jira]` section:

```bash theme={null}
[jira]
jira_base_url = "https://<JIRA_ORG>.atlassian.net"
```

Where `<JIRA_ORG>` is your Jira organization identifier (e.g., `mycompany` for `https://mycompany.atlassian.net`).

## Multi-JIRA server configuration

Qodo supports connecting to multiple JIRA servers using different authentication methods.

#### Email/token (basic auth)

Configure multiple servers using Email/Token authentication in your [configuration file](/v1/configuration/configuration-file).

**Example Configuration:**

```js theme={null}
[jira]
# List of Jira Server URLs
jira_servers = ["https://company.atlassian.net", "https://datacenter.jira.com"]

# List of API tokens (for Cloud) or passwords (for Data Center)
jira_api_token = ["cloud_api_token_here", "datacenter_password"]

# List of emails (for Cloud) or usernames (for Data Center)
jira_api_email = ["user@company.com", "datacenter_username"]

# Default server for ticket IDs
# Each repository can configure its own jira_base_url in a local config file
# to choose which server to use by default.
jira_base_url = "https://company.atlassian.net"
```

#### PAT auth

Configure multiple servers using Personal Access Token authentication in your [configuration file](/v1/configuration/configuration-file).

**Example Configuration:**

```js theme={null}
[jira]
# List of JIRA server URLs
jira_servers = ["https://server1.jira.com", "https://server2.jira.com"]

# List of PAT tokens
jira_api_token = ["pat_token_1", "pat_token_2"]

# Default server for ticket IDs
# Each repository can configure its own jira_base_url in a local config file
# to choose which server to use by default.
jira_base_url = "https://server1.jira.com"
```

**Mixed Authentication (Email/Token + PAT):**

```js theme={null}
[jira]
jira_servers = ["https://company.atlassian.net", "https://server.jira.com"]
jira_api_token = ["cloud_api_token", "server_pat_token"]
jira_api_email = ["user@company.com", ""]  # Empty for PAT
```

#### Jira Cloud app

For Jira Cloud instances using App Authentication:

<Steps>
  <Step>
    Install the Qodo app on each JIRA Cloud instance you want to connect to.
  </Step>

  <Step>
    In your [configuration file](/v1/configuration/configuration-file), set the default server for ticket ID resolution:

    ```bash theme={null}
    [jira]
    jira_base_url = "https://primary-team.atlassian.net"
    ```
  </Step>
</Steps>

Full URLs (e.g., `https://other-team.atlassian.net/browse/TASK-456`) will automatically use the correct connected instance.