PR validation using linked issues

CodeRabbit provides intelligent assessment of linked issues to validate whether pull requests properly address their requirements. This guide explains how to effectively use linked issues and write clear issue descriptions for optimal results.

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, GitLab, Jira, and Linear, CodeRabbit detects references in the pull request description using platform-specific syntax:

GitHub

fixes #123
closes #123
resolves #123

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 them against your pull request changes to determine if the requirements are met:

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 identifies a missing requirement from the linked issue

Best practices for issue writing

Issue titles

Create descriptive, technical titles that clearly state the goal:

Good examples

• “Add PrismaLint integration to configuration flow”
• “Fix race condition in user authentication”
• “Implement caching for GraphQL queries”

Poor examples

• “Fix bug”
• “Update code”
• “Improve performance”

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:

Problem:
The configuration system doesn't validate Prisma schema files before deployment,
leading to potential runtime errors.

Solution:
Integrate PrismaLint into the configuration flow to:

- Validate schema files during PR checks
- Enforce consistent naming conventions
- Prevent common Prisma anti-patterns

Affected Components:

- Configuration validation pipeline
- CI/CD workflow
- Schema validation logic

Acceptance Criteria:

- [ ] PrismaLint runs on all PR checks
- [ ] Failed validations block merging
- [ ] Clear error messages for schema issues

Consistent terminology

Use consistent terminology between issues and pull requests:

Good practices

• Use the same technical terms consistently
• Reference components with their exact names
• Maintain consistent naming patterns

Poor practices

• Mixing different terms for the same component
• Using vague or non-technical language
• Inconsistent capitalization or formatting

Linking issues effectively

In pull requests

Direct references

Fixes #123
Resolves organization/repo#456
Closes https://github.com/org/repo/issues/789

Multiple issues

This PR addresses:
- Fixes #123
- Closes #456
- Resolves https://jira.company.com/browse/PROJ-789

Cross-references

For better traceability:

1. Add PR references in issue comments

   Link back to the pull request from the issue discussion

2. Use complete URLs for external systems

   Include full URLs when referencing Jira, Linear, or other platforms

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 are not currently analyzed.

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

Related resources

Review instructions

Learn how to add custom instructions to your reviews

Issue creation

Automatically create issues from PR reviews

Issue trackers

Set up Jira or Linear integrations for linked issues