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

# Jira

> Connect your Jira workspace to keep issues and pull requests in sync

export const ThemeImage = ({src, alt}) => {
  let lightSrc, darkSrc;
  if (src.includes("-light.")) {
    lightSrc = src;
    darkSrc = src.replace("-light.", "-dark.");
  } else if (src.includes("-dark.")) {
    darkSrc = src;
    lightSrc = src.replace("-dark.", "-light.");
  } else {
    lightSrc = src;
    darkSrc = src;
  }
  return <span>
      <img className="block dark:hidden rounded-lg border" src={lightSrc} alt={alt} />
      <img className="hidden dark:block rounded-lg border" src={darkSrc} alt={alt} />
    </span>;
};

## Overview

The Gitar Jira Integration seamlessly connects Jira issues with your pull requests. Gitar can read issues, update status, and add comments — keeping project management and code reviews in sync.

<CardGroup cols={2}>
  <Card title="Auto-Link Issues" icon="link">
    Detect and link Jira issues even when ticket references are missing
  </Card>

  <Card title="Post Merge Summaries" icon="file-text">
    Add implementation summaries to linked issues when PRs merge
  </Card>

  <Card title="Suggest Reviewers" icon="users">
    Suggest reviewers based on Jira watchers and stakeholders
  </Card>

  <Card title="Create Follow-ups" icon="plus-circle">
    Create follow-up issues for unresolved comments and new TODOs
  </Card>
</CardGroup>

## Authentication Methods

Gitar supports two ways to authenticate with Jira:

### OAuth 2.0 (Recommended)

OAuth provides secure, one-click authentication with automatic token refresh. No manual token management required.

### Personal Access Token (PAT)

Personal Access Tokens provide direct API access with manual token management.

## Get Started with OAuth

Follow these steps to connect your Jira workspace using OAuth 2.0 (recommended).

<Note title="OAuth App Setup Required">
  Before connecting with OAuth, ensure your organization has configured the Gitar OAuth app in the [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/). Contact your administrator if you need access or assistance with OAuth app configuration.
</Note>

<Steps>
  <Step title="Access Gitar Integrations">
    Navigate to your organization's settings in the Gitar dashboard to begin the integration:

    1. Navigate to your organization's **Settings** in the Gitar dashboard
    2. Go to the **Integrations** section
    3. Find the **Jira** card under **Ticketing & Documentation** and click **Connect**

    <ThemeImage src="/assets/images/integrations/1-click-jira-connect-dark.png" alt="Jira integration card in Gitar settings" />
  </Step>

  <Step title="Select OAuth Authentication">
    In the Jira connection dialog, you'll see two authentication options:

    <ThemeImage src="/assets/images/integrations/2-show-both-oauth-pat-dark.png" alt="Jira authentication options - OAuth and PAT tabs" />

    1. Select the **OAuth** tab
    2. Click **Connect with OAuth**

    <ThemeImage src="/assets/images/integrations/3-oauth-select-connect-with-oauth-dark.png" alt="OAuth authentication selection in Jira integration dialog" />
  </Step>

  <Step title="Authorize with Atlassian">
    You'll be redirected to Atlassian's authorization page:

    1. Select your Atlassian site
    2. Review the permissions requested
    3. Click **Accept** to authorize Gitar

           <img src="https://mintcdn.com/gitar/55tETi2OXLxB8EgX/assets/images/integrations/4-oauth-atlassian-oauth-app-connect-bot.png?fit=max&auto=format&n=55tETi2OXLxB8EgX&q=85&s=df85327d62249d7594f75a5948953ebb" alt="Atlassian OAuth authorization page" width="1000" height="1606" data-path="assets/images/integrations/4-oauth-atlassian-oauth-app-connect-bot.png" />
  </Step>

  <Step title="Connection Successful">
    Once authorized, you'll see a confirmation that your Jira integration is connected.

    <ThemeImage src="/assets/images/integrations/5-oauth-jira-oauth-connected-dark.png" alt="Jira OAuth integration successfully connected" />
  </Step>
</Steps>

## Get Started with Personal Access Token

Follow these steps to connect using a Personal Access Token.

<Steps>
  <Step title="Generate a Jira API Token">
    Create a Personal Access Token in your Atlassian account:

    1. Go to [Atlassian API tokens page](https://id.atlassian.com/manage-profile/security/api-tokens)
    2. Click **Create API token**
    3. Give it a descriptive name (e.g., "Gitar Integration")
    4. Copy the generated token (you won't be able to see it again)
  </Step>

  <Step title="Enter PAT Credentials">
    Return to the Gitar Jira integration dialog:

    1. Select the **Personal Access Token** tab
    2. Enter your **Jira Instance URL** (e.g., `https://your-company.atlassian.net`)
    3. Enter your **Jira User Email**
    4. Paste your **Personal Access Token**

    <ThemeImage src="/assets/images/integrations/1-PAT-email-token-dark.png" alt="Enter Jira PAT credentials form" />
  </Step>

  <Step title="Save Configuration">
    After entering all the required information:

    1. Review your credentials
    2. Click **Save** to complete the connection

    <ThemeImage src="/assets/images/integrations/2-PAT-credentials-entered-click-connect-dark.png" alt="PAT credentials ready to save" />
  </Step>

  <Step title="Connection Successful">
    Your Jira PAT integration is now active and ready to use.

    <ThemeImage src="/assets/images/integrations/3-PAT-connected-dark.png" alt="Jira PAT integration successfully connected" />
  </Step>
</Steps>

## Frequently Asked Questions

### What permissions does Gitar need?

For OAuth, Gitar requests:

* Read Jira issues and user information
* Write to Jira (create/update issues, add comments)
* Offline access (for automatic token refresh)

### How often are OAuth tokens refreshed?

OAuth tokens are automatically refreshed before they expire to maintain continuous connectivity. No manual intervention required.

### What happens if my PAT expires?

You'll need to generate a new token and update it in Gitar by going to **Settings** → **Integrations** → **Jira** → **Configure**.

## Enable Jira Features

Once your Jira integration is connected, you can enable specific features through your repository's Rules page:

1. Navigate to your repository in the Gitar dashboard
2. Go to **Rules** in the sidebar
3. Find the Jira-related rules and toggle them on

<ThemeImage src="/assets/images/integrations/jira-rules-light.png" alt="Jira rules configuration in Gitar dashboard" />