Migration Guide

This guide helps you migrate from existing dependency management tools like Renovate and Dependabot to Buddy.

Quick Migration

Buddy includes automated migration capabilities to ease the transition from other tools.

Interactive Migration

Run the setup command to automatically detect and migrate existing configurations:

buddy setup

This will:

• 🔍 Detect existing Renovate and Dependabot configurations
• ⚙️ Convert settings to Buddy format
• 📋 Generate migration report with compatibility notes
• 🚀 Setup new workflows and configuration

Supported Migration Sources

Tool-Specific Guides

For detailed migration instructions, see the dedicated guides:

• 📝 Renovate Migration → - Comprehensive guide for migrating from Renovate
• 📝 Dependabot Migration → - Complete Dependabot to Buddy migration

Quick Examples

Basic Renovate Migration

// renovate.json
{
  "extends": ["config:base"],
  "schedule": ["before 6am"],
  "automerge": true,
  "ignoreDeps": ["react"]
}

// buddy.config.ts
export default {
  schedule: { cron: '0 4 * * *', timezone: 'UTC' },
  packages: { strategy: 'all', ignore: ['react'] },
  pullRequest: { autoMerge: { enabled: true, strategy: 'squash' } }
} satisfies BuddyConfig

Basic Dependabot Migration

# .github/dependabot.yml
version: 2
updates:

  - package-ecosystem: "npm"

    directory: "/"
    schedule:
      interval: "weekly"

// buddy.config.ts
export default {
  schedule: { cron: '0 2 * * 1', timezone: 'UTC' },
  packages: { strategy: 'all' }
} satisfies BuddyConfig

Migration Mapping

Schedule Conversion

Update Strategy Mapping

Grouping & Patterns

Configuration Examples

Conservative Migration

For teams wanting minimal disruption:

export default {
  schedule: {
    cron: '0 2 * * 1', // Weekly Monday 2 AM
    timezone: 'UTC'
  },
  packages: {
    strategy: 'patch', // Only patch updates
    excludeMajor: true,
    ignore: [
      // Add packages you want to update manually
      'react',
      'typescript',
      '@types/node'
    ]
  },
  pullRequest: {
    autoMerge: {
      enabled: false // Manual review required
    },
    reviewers: ['@team-leads'],
    labels: ['dependencies', 'review-required']
  }
} satisfies BuddyConfig

Aggressive Migration

For teams wanting frequent updates:

A group only decides which packages share a pull request, so anything that varies by update type belongs in packages.rules instead:

export default {
  schedule: {
    cron: '0 2 * * *', // Daily 2 AM
    timezone: 'UTC'
  },
  packages: {
    strategy: 'all',
    includePrerelease: false, // Stable releases only
    rules: [
      {
        matchUpdateTypes: ['patch'],
        groupName: 'Patch Updates',
        autoMerge: true
      },
      {
        matchUpdateTypes: ['minor'],
        groupName: 'Minor Updates',
        schedule: '0 2 * * 1' // Only proposed on a Monday run
      },
      {
        matchUpdateTypes: ['major'],
        groupName: 'Major Updates',
        schedule: '0 2 1 * *', // Only proposed on a first-of-month run
        autoMerge: false
      }
    ]
  }
} satisfies BuddyConfig

A rule's schedule is a window rather than a trigger: the workflow's own cron decides when Buddy runs, and the rule decides whether these updates are allowed through on that run. See scheduling.

Workflow Migration

GitHub Actions Setup

Buddy automatically generates optimized GitHub Actions workflows:

# Run setup to generate workflows
buddy setup

# Generated files
# .github/workflows/buddy-dashboard.yml
# .github/workflows/buddy-check.yml
# .github/workflows/buddy-update.yml

Removing Old Configurations

After successful migration:

# Remove Renovate files
rm -f renovate.json .renovaterc .renovaterc.json

# Remove Dependabot config
rm -f .github/dependabot.yml .github/dependabot.yaml

# Remove package.json renovate config
# Edit package.json and remove "renovate" key

Validation & Testing

Dry Run Migration

Test your configuration before going live:

# Preview what would be updated
buddy scan --verbose

# Test update process without creating PRs
buddy update --dry-run

Gradual Rollout

1. Week 1: Setup Buddy alongside existing tool
2. Week 2: Compare PR quality and timing
3. Week 3: Disable old tool, monitor Buddy
4. Week 4: Remove old configurations

Troubleshooting

Common Issues

❌ Migration detected incompatible features

Solution: Review migration report warnings and manually configure advanced features

❌ Schedule conflicts

Solution: Disable old tool first, then setup Buddy schedules

❌ PR format differences

Solution: Customize PR templates in buddy.config.ts

Getting Help

• 📖 Check the Configuration Guide
• 🐛 Review GitHub Issues
• 💬 Ask in Discord

Best Practices

✅ Do

• Run migration during low-activity periods
• Test with dry-run first
• Keep old configurations until Buddy is proven stable
• Monitor first few weeks closely
• Document any custom configurations needed

❌ Don't

• Migrate during critical deployment periods
• Remove old tools immediately
• Ignore migration warnings
• Skip validation testing
• Forget to update team documentation

Next Steps

After migration:

1. 📊 Dashboard: Enable dependency dashboard for visibility
2. 🔧 Customize: Fine-tune grouping and scheduling
3. 🚀 Automate: Configure auto-merge for trusted updates
4. 📈 Monitor: Track update frequency and PR quality
5. 🎯 Optimize: Adjust strategies based on team workflow

The migration process ensures a smooth transition while maintaining your existing dependency management practices and improving upon them with Buddy's advanced features.