coderabbit-upgrade-migration

CodeRabbit Upgrade & Migration

Overview

CodeRabbit is a managed SaaS service -- there is no SDK to upgrade. Configuration changes happen by updating .coderabbit.yaml in your repository. This skill covers adopting new CodeRabbit features, upgrading between plans, migrating configuration formats, and staying current with CodeRabbit capabilities.

Prerequisites

• CodeRabbit installed on repository
• .coderabbit.yaml in repository root
• Access to CodeRabbit dashboard at app.coderabbit.ai

Upgrade Paths

From	To	What Changes
Free	Pro	Private repos, more concurrent reviews, all features
Pro	Enterprise	SSO, dedicated support, SLA, custom limits
Old config format	New format	Updated YAML schema fields
Basic config	Advanced config	Path instructions, learnings, finishing touches

Instructions

Step 1: Check Current Configuration vs Latest Schema

# On any open PR, post this comment:
@coderabbitai configuration

# CodeRabbit replies with the active config as YAML.
# Compare with the latest schema documentation to find:
# 1. Deprecated fields you're still using
# 2. New fields available that you're not using
# 3. Fields with changed default values

Step 2: Upgrade Free to Pro Plan

# What you gain with Pro:
1. Private repository support (Free = public only)
2. More concurrent reviews (Free = 1, Pro = 5)
3. Learnings (CodeRabbit remembers your feedback preferences)
4. Finishing Touches (auto-generate docstrings, custom recipes)
5. Full path instructions and review customization
6. Priority review processing

# Steps:
1. Go to app.coderabbit.ai > Organization > Subscription
2. Select Pro plan
3. Set seat assignment policy (active committers recommended)
4. Add payment method
5. Seats activate immediately for all configured repos

Step 3: Adopt New Configuration Features

# .coderabbit.yaml - Modern configuration with latest features

language: "en-US"
early_access: false              # Set true to try beta features

reviews:
  profile: "assertive"
  request_changes_workflow: true
  high_level_summary: true
  high_level_summary_in_walkthrough: true   # Summary inside walkthrough comment
  review_status: true
  collapse_walkthrough: false
  sequence_diagrams: true                    # Visual control flow diagrams
  poem: false

  auto_review:
    enabled: true
    drafts: false
    base_branches:
      - main
      - develop
    ignore_title_keywords:
      - "WIP"
      - "DO NOT MERGE"
      - "chore: bump"

  path_filters:
    - "!**/*.lock"
    - "!**/*.snap"
    - "!**/generated/**"
    - "!dist/**"
    - "!vendor/**"

  path_instructions:
    - path: "src/api/**"
      instructions: "Review for input validation, auth middleware, error handling."
    - path: "src/db/**"
      instructions: "Review for parameterized queries, transactions, N+1 patterns."
    - path: "**/*.test.*"
      instructions: "Review for edge cases. Skip style comments."
    - path: ".github/workflows/**"
      instructions: "Pin action versions to SHA. No secrets in logs."

  # Finishing Touches (Pro+)
  finishing_touches:
    docstrings:
      enabled: true              # @coderabbitai generate-docstrings command

  # Tool integrations
  tools:
    eslint:
      enabled: true              # Lint with ESLint rules
    biome:
      enabled: true              # Biome linter
    shellcheck:
      enabled: true              # Shell script linting
    markdownlint:
      enabled: true              # Markdown linting

# Tone customization (Pro+)
tone_instructions: |
  Be concise and direct. Use bullet points for multiple suggestions.
  Include code examples for non-obvious fixes.
  Rate severity: Critical > Warning > Suggestion > Nitpick.

chat:
  auto_reply: true

Step 4: Enable Finishing Touch Recipes

# .coderabbit.yaml - Custom finishing touch recipes (Pro+)
finishing_touches:
  docstrings:
    enabled: true

  recipes:
    - name: "fix-imports"
      description: "Sort and organize imports"
      instructions: |
        Sort all imports alphabetically. Group: external packages first,
        then internal modules, then relative imports. Remove unused imports.

    - name: "tighten-types"
      description: "Replace any with proper types"
      instructions: |
        Replace all `any` types with proper TypeScript types.
        Use `unknown` for truly unknown values. Add type guards where needed.

    - name: "add-error-handling"
      description: "Add missing error handling"
      instructions: |
        Add try/catch blocks to async operations that are missing error handling.
        Include meaningful error messages and proper error propagation.

# Use recipes on a PR:
@coderabbitai run fix-imports
@coderabbitai run tighten-types
@coderabbitai generate-docstrings

# Or check the boxes in the Finishing Touches section of the walkthrough comment

Step 5: Enable Early Access Features

# .coderabbit.yaml - Opt into beta features
early_access: true    # Enables experimental features as they ship

# Early access features are documented at:
# https://docs.coderabbit.ai/early-access
#
# Recent early access features have included:
# - Finishing touch recipes (now GA)
# - Tool integrations (eslint, biome, shellcheck)
# - Sequence diagrams in walkthroughs
# - Knowledge base / code guidelines auto-detection

Step 6: Validate After Upgrade

set -euo pipefail

echo "=== Post-Upgrade Validation ==="

# 1. Validate YAML syntax
echo "--- YAML Validation ---"
python3 -c "
import yaml
config = yaml.safe_load(open('.coderabbit.yaml'))
print(f'YAML: VALID ({len(str(config))} chars)')

# Check for new features
reviews = config.get('reviews', {})
ft = reviews.get('finishing_touches', {})
tools = reviews.get('tools', {})
tone = config.get('tone_instructions', '')
early = config.get('early_access', False)

print(f'Finishing touches: {\"enabled\" if ft else \"not configured\"}')
print(f'Tool integrations: {len(tools)} tools configured')
print(f'Tone instructions: {\"set\" if tone else \"default\"}')
print(f'Early access: {early}')
" 2>&1

# 2. Verify config is active
echo ""
echo "--- Verify on PR ---"
echo "Post '@coderabbitai configuration' on any open PR to verify"
echo "the new configuration is active."

Step 7: Migration Checklist

# When updating configuration:
- [ ] YAML syntax validated before committing
- [ ] Config committed to main branch (CodeRabbit reads from base branch)
- [ ] @coderabbitai configuration verified on a test PR
- [ ] Team notified of any behavior changes
- [ ] Old deprecated fields removed
- [ ] New features tested on a non-critical PR first

Output

• Configuration updated to latest CodeRabbit schema
• New features (finishing touches, tool integrations, tone) enabled
• Plan upgrade completed (if applicable)
• Post-upgrade validation passed
• Migration checklist completed

Error Handling

Issue	Cause	Solution
New field ignored	Not on Pro/Enterprise plan	Upgrade plan for full feature access
Config not applied after update	Committed to wrong branch	Merge config changes to the base branch
YAML parse error	Invalid syntax	Validate YAML before committing
Feature not available	Requires early_access: true	Enable early access in config
Finishing touches not working	Not on Pro plan	Upgrade to Pro for finishing touches

Resources

• CodeRabbit Changelog
• CodeRabbit Configuration Reference
• CodeRabbit Pricing
• CodeRabbit Early Access
• Finishing Touches

Next Steps

For CI integration after upgrade, see coderabbit-ci-integration.