Configuration

Buddy can be configured through a TypeScript configuration file for full type safety.

Configuration File

Create a buddy.config.ts file in your project root:

import type { BuddyConfig } from '@buddysh/buddy'

const config: BuddyConfig = {
  verbose: false,

  repository: {
    provider: 'github',
    owner: 'your-org',
    name: 'your-repo',
    token: process.env.GITHUB_TOKEN,
    baseBranch: 'main'
  },

  packages: {
    strategy: 'all',
    ignore: ['legacy-package'],
    groups: []
  },

  pullRequest: {
    titleFormat: 'chore(deps): {title}',
    commitMessageFormat: 'chore(deps): {message}',
    labels: ['dependencies'],
    reviewers: [],
    autoMerge: { enabled: false }
  },

  dashboard: {
    enabled: true,
    title: 'Dependency Dashboard',
    pin: true
  }
}

export default config

Repository Settings

Configure how Buddy interacts with your repository:

repository: {
  // Git provider
  provider: 'github', // 'github' | 'gitlab' | 'bitbucket'

  // Repository owner (organization or user)
  owner: 'stacksjs',

  // Repository name
  name: 'buddy',

  // GitHub token for API access
  token: process.env.GITHUB_TOKEN,

  // Base branch for PRs
  baseBranch: 'main'
}

Package Settings

Control which packages get updated and how:

packages: {
  // Update strategy
  strategy: 'all', // 'all' | 'major' | 'minor' | 'patch'

  // Packages to ignore
  ignore: [
    'legacy-package',
    '@types/node'
  ],

  // Group related packages
  groups: [
    {
      name: 'TypeScript Types',
      patterns: ['@types/*'],
      strategy: 'minor'
    },
    {
      name: 'ESLint Ecosystem',
      patterns: ['eslint*', '@typescript-eslint/*'],
      strategy: 'patch'
    },
    {
      name: 'React',
      patterns: ['react', 'react-dom', '@types/react*'],
      strategy: 'minor'
    }
  ]
}

Package Groups

Grouping related packages creates single PRs for coordinated updates:

groups: [
  {
    // Group name (appears in PR title)
    name: 'Testing',

    // Glob patterns to match packages
    patterns: ['vitest', '@vitest/*', 'happy-dom'],

    // Strategy for this group (overrides global)
    strategy: 'minor'
  }
]

Pull Request Settings

Customize how PRs are created:

pullRequest: {
  // PR title format
  titleFormat: 'chore(deps): {title}',

  // Commit message format
  commitMessageFormat: 'chore(deps): {message}',

  // Reviewers to assign
  reviewers: ['maintainer1', 'maintainer2'],

  // Labels to apply
  labels: ['dependencies', 'automated'],

  // Auto-merge configuration
  autoMerge: {
    enabled: true,
    strategy: 'squash', // 'merge' | 'squash' | 'rebase'
    conditions: ['patch-only']
  }
}

Auto-Merge

Automatically merge PRs that meet conditions:

autoMerge: {
  enabled: true,

  // Merge strategy
  strategy: 'squash',

  // Conditions for auto-merge
  conditions: [
    'patch-only' // Only auto-merge patch updates
  ]
}

Dashboard Settings

Configure the dependency dashboard issue:

dashboard: {
  // Enable dashboard
  enabled: true,

  // Dashboard issue title
  title: 'Dependency Dashboard',

  // Pin issue to top
  pin: true,

  // Labels for the issue
  labels: ['dependencies', 'dashboard'],

  // Assignees for the issue
  assignees: ['maintainer1'],

  // Show open PRs in dashboard
  showOpenPRs: true,

  // Show detected dependencies
  showDetectedDependencies: true
}

Workflow Presets

Choose from predefined workflow configurations:

Standard (Default)

buddy setup --preset standard

• Dashboard updates 3x/week
• Balanced dependency updates

High Frequency

buddy setup --preset high-frequency

• Updates multiple times per day
• Auto-merge patch updates

Security Focused

buddy setup --preset security

• Frequent security patches
• Prioritizes vulnerability fixes

Minimal

buddy setup --preset minimal

• Weekly checks only
• Lower frequency

Testing

buddy setup --preset testing

• Every 5 minutes
• Dry run by default
• For development/testing

Migration from Other Tools

From Renovate

Buddy automatically migrates settings from:

• renovate.json
• .renovaterc
• package.json renovate config

buddy setup
# Detects and offers to migrate Renovate config

From Dependabot

Migrates from:

• .github/dependabot.yml
• .github/dependabot.yaml

Settings mapped:

• Schedule intervals
• Ignore patterns
• Package ecosystems

Integration Settings

Slack

export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."

Or create .buddy/slack-webhook:

https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK

Discord

export DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/..."

Jira

export JIRA_API_TOKEN="your-token"
export JIRA_BASE_URL="https://your-org.atlassian.net"
export JIRA_PROJECT_KEY="DEPS"

Custom Plugins

Create custom integrations in .buddy/plugins/:

// .buddy/plugins/custom-notify.json
{
  "name": "custom-notify",
  "version": "1.0.0",
  "enabled": true,
  "triggers": [
    { "event": "setup_complete" },
    { "event": "pr_created" }
  ],
  "configuration": {
    "webhook_url": "https://your-webhook.com/notify"
  }
}

Environment Configuration

Override settings via environment:

# Required for PR creation
export GITHUB_TOKEN="ghp_..."

# For updating workflow files
export BUDDY_TOKEN="ghp_..."

# Verbose output
export BUDDY_VERBOSE=true

Next Steps

• Learn about PR Generation customization
• See Usage Examples for advanced patterns