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

# Jira Integration

> Connect CodeRabbit to Jira to enrich pull request reviews with issue context, validate changes against acceptance criteria, create issues from review comments, and design Coding Plans.

export const Hint = ({type, children, headline, tip, href, cta}) => {
  const TIPS = {
    learnings: {
      headline: "Learnings",
      tip: "Review preferences CodeRabbit learns from your chat conversations and applies automatically to future reviews.",
      cta: "Learn about Learnings",
      href: "/knowledge-base/learnings",
      content: "Learnings"
    },
    walkthrough: {
      headline: "PR Walkthrough",
      tip: "A structured comment posted by CodeRabbit at the top of every pull request, summarizing changes, sequence diagrams, review effort, and more.",
      cta: "Learn about PR Walkthroughs",
      href: "/pr-reviews/walkthroughs",
      content: "Walkthrough"
    },
    "finishing-touches": {
      headline: "Finishing Touches",
      tip: "Post-review agentic actions (Autofix, writing docstrings or unit tests, and more) you trigger from a PR comment or a checkbox in the Walkthrough.",
      cta: "See all Finishing Touches",
      href: "/finishing-touches",
      content: "Finishing Touches"
    },
    "coding-plan": {
      headline: "Coding Plan",
      tip: "A detailed, codebase-aware implementation plan CodeRabbit generates from an issue or description, ready to hand off to any coding agent.",
      cta: "Learn about Coding Plans",
      href: "/plan",
      content: "Coding Plan"
    },
    "knowledge-base": {
      headline: "Knowledge Base",
      tip: "The collected context sources CodeRabbit draws on during reviews: Learnings, Code Guidelines, issue trackers, connected MCP servers, and cross-repo analysis.",
      cta: "Explore the Knowledge Base",
      href: "/knowledge-base",
      content: "Knowledge Base"
    },
    "path-instructions": {
      headline: "Path Instructions",
      tip: "Custom review rules that only apply to files matching a glob pattern, e.g. 'src/controllers/**'.",
      cta: "Configure path instructions",
      href: "/configuration/path-instructions",
      content: "Path Instructions"
    },
    "change-stack": {
      headline: "Change Stack",
      tip: "An improved code inspection interface that reorganizes a pull request from a flat file list into a structured, layer-by-layer walkthrough with range-specific summaries and diagrams when useful.",
      cta: "Learn about Change Stack",
      href: "/change-stack",
      content: "Change Stack"
    },
    scope: {
      headline: "Scope",
      tip: "A named set of repositories, connections, and spend limits that controls what CodeRabbit Agent can access in a given Slack conversation.",
      cta: "Learn about Scopes",
      href: "/slack-agent/scopes",
      content: "Scope"
    },
    "coderabbit-agent": {
      headline: "CodeRabbit Agent for Slack",
      tip: "An AI agent built into Slack that investigates issues, generates implementation plans, and opens pull requests right from the Slack threads.",
      cta: "Explore CodeRabbit Agent",
      href: "/slack-agent",
      content: "CodeRabbit Agent"
    },
    "configuration-inheritance": {
      headline: "Configuration Inheritance",
      tip: "A setting that merges configuration values across multiple levels — repository YAML, central YAML, and UI settings — instead of using only the highest-priority source.",
      cta: "Learn about Configuration Inheritance",
      href: "/configuration/configuration-inheritance",
      content: "Configuration Inheritance"
    }
  };
  const defaults = TIPS[type] || ({});
  return <Tooltip headline={headline ?? defaults.headline} tip={tip ?? defaults.tip} cta={cta ?? defaults.cta} href={href ?? defaults.href}>
      {children ?? defaults.content}
    </Tooltip>;
};

export const EssentialsPlanBadge = ({tip = "This feature is available on Essentials (formerly Pro), Team (formerly Pro+), Advanced, and Enterprise. Please refer to our pricing page for more information about our plans and features.", title = "Essentials Plan", cta = "Read more", href = "https://coderabbit.ai/pricing", disabled = false}) => {
  return <Tooltip tip={tip} cta={cta} href={href}>
        <Badge icon="shield-check" disabled={disabled || undefined}>
            {title}
        </Badge>
    </Tooltip>;
};

export const AllPlatformsBadge = ({tip = "This feature is available on all supported platforms: GitHub, GitLab, Azure DevOps, and Bitbucket.", title = "All Platforms", cta, href, disabled = false}) => {
  return <Tooltip tip={tip} cta={cta} href={href}>
        <Badge icon="globe" disabled={disabled || undefined}>
            {title}
        </Badge>
    </Tooltip>;
};

<AllPlatformsBadge /> | <EssentialsPlanBadge />

## Overview

The Jira integration connects CodeRabbit to your Jira workspace, bringing issue context into every stage of development. Here's what the integration enables:

<CardGroup cols={2}>
  <Card title="Context enrichment" icon="book-open" horizontal="true" href="/issues/pr-validation">
    Pulls in Jira issue details so CodeRabbit understands *why* a change is
    being made
  </Card>

  <Card title="Requirement validation" icon="clipboard-check" horizontal="true" href="/issues/pr-validation">
    Assesses whether code changes address the linked issue's acceptance criteria
  </Card>

  <Card title="Issue planning" icon="layout-list" horizontal="true" href="/issues/planner">
    Generates step-by-step <Hint type="coding-plan">Coding Plans</Hint> from Jira issues for coding agents and
    IDE copilots
  </Card>

  <Card title="Issue creation" icon="square-plus" horizontal="true" href="/issues/creation">
    Creates new Jira issues directly from PR review comments
  </Card>
</CardGroup>

## Prerequisites

Before setting up the Jira integration, ensure you have:

* A **Jira Cloud** account (for Jira Data Center or self-hosted, see [Jira Data Center](#jira-data-center-self-hosted) below)
* Admin access to install apps on your Jira site
* A CodeRabbit Essentials plan

## Install the Jira Cloud integration

The Jira Cloud integration uses a Forge app from the Atlassian Marketplace. Follow these steps to connect your Jira site to CodeRabbit:

<Steps>
  <Step title="Add a Jira connection in CodeRabbit">
    Open [Connections](https://app.coderabbit.ai/connections), select **Add connection**, choose **Jira**, and select **Direct connection** for Review.
  </Step>

  <Step title="Copy the installation secret">
    A modal appears with setup instructions and an **Installation Secret**
    (valid for 15 minutes). Copy the secret, then click **Open Atlassian
    Installation**.
  </Step>

  <Step title="Install from Atlassian Marketplace">
    On the Atlassian Marketplace page for the CodeRabbit app, click **Get app**.
  </Step>

  <Step title="Select your Jira site">
    Choose which Jira site to install the CodeRabbit app on and click
    **Install**.
  </Step>

  <Step title="Open Jira app settings">
    In your Jira site, click the **Settings** gear icon and select **Marketplace
    apps**.
  </Step>

  <Step title="Complete the setup">
    Under **Apps**, select **CodeRabbit**. On the CodeRabbit Setup page, paste
    the Installation Secret you copied earlier and click **Complete Setup**.
  </Step>

  <Step title="Verify the integration">
    Return to CodeRabbit and click **Refresh Status** to confirm the integration
    is connected.
  </Step>

  <Step title="Add the connection to the Review Base Scope">
    If you did not add the connection to the Review Base Scope during setup, open [Review scopes](/connections/scopes-review) and select it there.
  </Step>
</Steps>

<Info>
  The Installation Secret expires after 15 minutes. If it expires before you
  complete the setup, start the process again from step 1.
</Info>

## Jira Data Center (Self-Hosted)

### Authentication and permissions

Jira Data Center uses a personal access token (PAT) with its REST API v2 client. The PAT does not use OAuth-style selectable scopes; it inherits the permissions of the Jira user who issues it. Use a dedicated CodeRabbit service account so you can scope and audit its access independently.

Grant the integration user these permissions:

* **Access tickets and manage webhooks (required)**: Grant read and search access to every project and issue CodeRabbit should use, including issue details, comments, and attachments. The user must also be able to manage webhooks. During setup, CodeRabbit checks the Jira server and registers its webhook; the connection cannot be saved if Jira rejects the webhook registration.
* **Create issues (recommended)**: Grant issue-creation permission only if you want users to create Jira issues through CodeRabbit.
* **Add comments (recommended)**: Grant comment-creation permission for Jira-triggered Issue Planner acknowledgments, errors, and plan-ready replies.
* **Update comments (recommended)**: Grant permission to update comments created by the integration user so CodeRabbit can update its Jira response comment.

The webhook subscribes to `issue-created`, `issue-updated`, `comment-created`, `comment-updated`, and `comment-deleted` events. Jira 9 uses the older webhook API and subscribes only to `issue-created` and `issue-updated` events.

### Network access

Your Jira Data Center instance must allow inbound HTTPS connections from CodeRabbit's outbound IP addresses. If your Jira Data Center instance requires IP allowlisting, add these CodeRabbit IP addresses:

<CodeGroup>
  ```text IPs to allow list theme={null}
  35.222.179.152/32, 34.170.211.100/32, 136.113.208.247/32
  ```
</CodeGroup>

### Integration behavior

| Capability             | Behavior                                                                                                                                                       |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Enrichment**         | Searches Jira and reads issue details, comments, and attachments to add context to code reviews.                                                               |
| **Validation**         | Reads the linked issue's title, description, and readable named custom fields, such as acceptance criteria, to validate code changes against its requirements. |
| **Planning**           | Posts acknowledgments, errors, and plan-ready replies for Jira-triggered Issue Planner workflows, and can update its own response comment.                     |
| **Creation**           | Creates a Jira issue only when a user explicitly requests issue creation from a review.                                                                        |
| **Webhook management** | Registers and manages the CodeRabbit webhook during self-hosted integration setup.                                                                             |
| **Status transitions** | Does not transition Jira issues or update their statuses. **Transition Issues** permission is not required.                                                    |

## Configure CodeRabbit for Jira

After connecting Jira, use `project_keys` to allow specific Jira projects and `excluded_project_keys` as the deny override. The project key is the prefix that appears before issue numbers—for example, if your issue URL is `https://company.atlassian.net/browse/PROJ-123`, the project key is `PROJ`.

Excluded project keys are never used as CodeRabbit context, regardless of repository allowlists. Exclusions are managed as a workspace-level security policy and always take precedence over `project_keys`.

<Tabs>
  <Tab title="YAML Configuration">
    Add the `project_keys` setting under `knowledge_base.jira` in your `.coderabbit.yaml` file:

    ```yaml .coderabbit.yaml theme={null}
    	knowledge_base:
    	jira:
    		usage: "enabled"
    		project_keys:
    		- "PROJ"
    		- "DEV"
    		- "BACKEND"
    		excluded_project_keys:
    		- "SECURITY"
    		- "HR"

    	chat:
    	integrations:
    		jira:
    		usage: "enabled"
    		issue_template: |
    			## Goal
    			## Description
    			## Acceptance Criteria
    ```

    The `usage` setting controls when the integration is active:

    * `auto` (default): Disabled for public repositories, enabled for private repositories
    * `enabled`: Always enabled
    * `disabled`: Always disabled

    The `issue_template` setting is a free-form string that shapes the description CodeRabbit writes for Jira issues created from chat - it doesn't control issue creation generally. CodeRabbit adds it to the Jira agent prompt and instructs the model to preserve the headings, keep their order, and fill each section from the request and PR context.

    The recommended content is Markdown headings, one per line, up to 3,000 characters; leave the setting empty to let CodeRabbit choose the structure. You can also include structural Markdown such as bullets, checkboxes, and fixed boilerplate text.

    <Warning>
      Direct instructions in `issue_template` about project, issue type, labels, assignee, or custom fields are technically accepted and may influence the model, but they aren't a reliable control channel. Keep `issue_template` limited to description guidance; instructions of that kind may be ignored or may accidentally appear in the description itself.
    </Warning>

    The resulting Markdown description is passed to Jira; Jira Cloud converts it to Atlassian Document Format (ADF).
  </Tab>

  <Tab title="Web Interface">
    1. Navigate to your repository or organization settings in the [CodeRabbit app](https://app.coderabbit.ai)
    2. Go to **Configuration** → **Knowledge Base**
    3. Under **Jira**, add the project keys CodeRabbit may use and the project keys to exclude
    4. Save the configuration

    <Frame caption="Jira configuration in the web interface">
      <img src="https://mintcdn.com/coderabbit/uoIgR95ZzO6NC8D5/images/assets/images/jira-integration-setup.png?fit=max&auto=format&n=uoIgR95ZzO6NC8D5&q=85&s=db91ab1b370ce0f69a49874098f62687" alt="Jira integration setup showing project key configuration" width="1580" height="1146" data-path="images/assets/images/jira-integration-setup.png" />
    </Frame>
  </Tab>
</Tabs>

<Info>
  By default, Jira integration is enabled for private repositories and disabled
  for public repositories. You can override this behavior by setting
  `knowledge_base.jira.usage: enabled` and `chat.integrations.jira.usage:
    	enabled` in your `.coderabbit.yaml` file or using the web interface. See the
  [Configuration reference](/reference/configuration) for details.
</Info>

## Example usage

### Linking Jira issues to pull requests

To have CodeRabbit validate requirements from a Jira issue, include the issue URL in your pull request description:

```md theme={null}
This PR implements the user authentication flow.

Closes https://company.atlassian.net/browse/PROJ-123
```

CodeRabbit will fetch the issue details and assess whether your code changes address the requirements specified in the issue. See the [Linked issues guide](/issues/pr-validation) for best practices on linking issues.

### Creating Jira issues from reviews

During a code review, you can ask CodeRabbit to create a Jira issue by mentioning `@coderabbitai` in a comment:

```md theme={null}
@coderabbitai create a Jira issue for this technical debt in the PROJ project
```

You can also name a parent when asking CodeRabbit to create a Jira sub-task or another issue. CodeRabbit resolves the parent to a Jira issue key and creates the new issue in the parent's project. Sub-task issue types are supported, and you can select one for the new issue.

```md theme={null}
@coderabbitai create a sub-task under PROJ-123 to add regression coverage for this issue
```

<Warning>
  Creating an issue on a Jira board or in a sprint may require Jira Software board or sprint permissions.
</Warning>

CodeRabbit creates a well-structured issue with relevant context from the code review discussion. See the [Issue creation guide](/issues/creation) for more details.

To standardize the descriptions of Jira issues created from chat, configure `chat.integrations.jira.issue_template` as shown in [Configure CodeRabbit for Jira](#configure-coderabbit-for-jira).

## Related resources

<Card title="Requirement validation" icon="link" horizontal="true" href="/issues/pr-validation">
  Best practices for linking issues to pull requests
</Card>

<Card title="Issue Planning" icon="layout-list" horizontal="true" href="/issues/planner">
  Generate Coding Plans from issues for coding agents
</Card>

<Card title="Issue creation" icon="square-plus" horizontal="true" href="/issues/creation">
  Create issues directly from CodeRabbit reviews
</Card>