Skip to main content
To use linked issues with Jira or Linear, you must first enable the corresponding integration. Note that these integrations are enabled for private repositories by default, but disabled for public repositories. See Issue trackers for setup instructions.

​
Understanding linked issues

A linked issue can be referenced in pull request text or attached through a platform-native link. For GitHub and GitLab, CodeRabbit detects references in the pull request description using platform-specific syntax. For Jira and Linear, it finds issue keys in the pull request title, the description, and the source branch name, as described in Jira and Linear issue keys:

​
Jira and Linear issue keys

CodeRabbit looks for Jira and Linear issue keys in three places: An issue key is a project or team key, a hyphen, and a number, such as PROJ-123. The project or team key is 2–20 characters long, starts with a letter, and contains only letters, digits, or underscores. Version-like strings such as v-1.2 don’t match, and lowercase text such as patch-1 in the title or description doesn’t match. In the title or description, a key joined to a preceding word with a hyphen, such as fix-PROJ-123, doesn’t match either. In a branch name, separate the key from the other words with / or -. An underscore next to the key prevents the match, so feature_proj-123_login finds nothing. CodeRabbit keeps a key only when its prefix matches a project on the connected Jira site or a team in the connected Linear workspace. For example, zod-4 in a branch name is ignored unless a ZOD project exists. Jira projects listed in excluded_project_keys are left out. If CodeRabbit can’t get the project or team list, it keeps the keys from the title and description and ignores the keys found only in the branch name. With self-hosted CodeRabbit connected to Jira, CodeRabbit doesn’t check keys against a project list. It looks up each key directly and ignores a key that doesn’t exist, without an error. CodeRabbit treats each issue it finds as either the work of the pull request or background context:
  • Direct target: a key in the title, a key in the branch name, or a key or URL in the description on a line that starts with Closes, Fixes, Resolves, or Refs. Close, Closed, Fix, Fixed, Resolve, Resolved, Ref, and References work too. The line can be a - bullet and can list several issues separated by commas, and, or &, such as Fixes PROJ-123, PROJ-124. These lines don’t count inside code blocks or block quotes.
  • Background context: any other key or issue URL in the description. CodeRabbit reads the issue, but it doesn’t add the issue’s requirements and doesn’t fail the linked issue assessment because of it.
A closed or inactive issue is background context, even when it’s a direct target.

​
Azure DevOps linked work items

For Azure DevOps, CodeRabbit also uses work items attached through Azure DevOps’ native Development / linked-work-items interface. This path does not require the pull request title, description, or branch name to mention the work item. Native links are handled separately from PR-text references; the text-reference formats above continue to work for the other platforms. CodeRabbit adds the linked work item’s title, description, state, tags, project, creator, timestamps, and URL to the review context. It uses up to 200 valid linked work items. Deleted or permission-restricted work items are omitted without discarding the remaining linked-work-item context. When CodeRabbit detects linked issues, it analyzes the ones the pull request targets against your changes to determine if the requirements are met. Jira and Linear issues that are only background context add no requirements:
Example of a linked Linear issue with summary, technical notes, and acceptance criteria

A well-structured Linear issue with clear acceptance criteria

If a requirement from the linked issue isn’t addressed, CodeRabbit flags it during review:
CodeRabbit review comment showing a potential issue where a linked issue requirement was not addressed

CodeRabbit identifies a missing requirement from the linked issue

​
Best practices for issue writing

​
Issue titles

Create descriptive, technical titles that clearly state the goal:
  • “Add PrismaLint integration to configuration flow”
  • “Fix race condition in user authentication”
  • “Implement caching for GraphQL queries”

​
Issue descriptions

Write comprehensive descriptions that provide clear technical context:
1

Problem statement

  • Clearly describe what needs to be changed
  • Include technical details about affected components
  • Reference specific files or functions if known
2

Expected solution

  • Outline the desired implementation approach
  • Include code examples or pseudo-code when relevant
  • List specific acceptance criteria
Example description:

​
Consistent terminology

Use consistent terminology between issues and pull requests:
  • Use the same technical terms consistently
  • Reference components with their exact names
  • Maintain consistent naming patterns

​
Linking issues effectively

​
In pull requests

​
Cross-references

For better traceability:
1

Add PR references in issue comments

Link back to the pull request from the issue discussion
2

Make Jira and Linear issues direct targets

Put the issue key in the pull request title or the branch name, or write a line such as Fixes PROJ-123 in the description. Other keys in the description are only background context. In a branch name, separate the key with / or -, not _.
3

Maintain bidirectional links

Ensure related issues reference each other for complete context

​
How CodeRabbit assesses linked issues

CodeRabbit evaluates linked issues through this process:
1

Analyze issue content

Reviews issue titles and descriptions for requirements and context. For Jira issues, this also includes named custom fields
2

Compare PR changes

Examines the code changes in the pull request
3

Validate requirements

Determines if the changes meet the stated objectives
4

Provide assessment

Returns one of three possible outcomes:
  • ✅ Addressed: Objective completed (no explanation needed)
  • ❌ Not addressed: Objective not met (explanation provided)
  • ❓ Unclear: Uncertain if objective is met (explanation provided)
The issue title, description, and, for Jira issues, named custom fields are considered in the assessment. Comments and discussion threads aren’t part of the assessment.

​
Tips for better assessments

Be specific

  • Include clear, measurable objectives
  • List specific technical requirements
  • Reference affected code components

Provide context

  • Explain why changes are needed
  • Document current behavior
  • Describe expected outcomes

Use technical details

  • Include file paths when known
  • Reference specific functions or classes
  • Mention relevant technologies

Keep it focused

  • One main objective per issue
  • Clear scope boundaries
  • Specific acceptance criteria

​
What’s next

Review instructions

Add custom instructions to guide how CodeRabbit reviews your pull requests

Issue creation

Create issues from pull request review comments

Issue trackers

Set up Jira or Linear integrations for linked issues