Configuration Types

TypeScript interfaces and types for buddy configuration.

Core Configuration

BuddyConfig

Main configuration interface for buddy.

interface BuddyConfig {
  /** Repository configuration */
  repository?: RepositoryConfig

  /** Package management settings */
  packages?: PackageConfig

  /** Pull request configuration */
  pullRequest?: PullRequestConfig

  /** Scheduling configuration */
  schedule?: ScheduleConfig

  /** Release notes configuration */
  releaseNotes?: ReleaseNotesConfig

  /** Git provider settings */
  git?: GitProviderConfig

  /** Registry configuration */
  registries?: RegistryConfig[]

  /** Global settings */
  global?: GlobalConfig
}

Repository Configuration

RepositoryConfig

Repository-specific settings.

interface RepositoryConfig {
  /** Repository owner/organization */
  owner: string

  /** Repository name */
  name: string

  /** Default branch */
  defaultBranch?: string

  /** Repository URL */
  url?: string

  /** Clone configuration */
  clone?: {
    depth?: number
    sparse?: boolean
    submodules?: boolean
  }
}

Package Configuration

PackageConfig

Package management and update configuration.

interface PackageConfig {
  /** Update strategy */
  strategy?: UpdateStrategy

  /** Package manager to use */
  manager?: PackageManager

  /** Packages to ignore */
  ignore?: string[]

  /** Package groups */
  groups?: PackageGroup[]

  /** Workspace configuration */
  workspaces?: WorkspaceConfig

  /** Version constraints */
  constraints?: Record<string, string>

  /** Include/exclude patterns */
  include?: string[]
  exclude?: string[]
}

UpdateStrategy

Available update strategies.

type UpdateStrategy = 'patch' | 'minor' | 'major' | 'all'

PackageManager

Supported package managers.

type PackageManager = 'bun' | 'npm' | 'yarn' | 'pnpm' | 'auto'

PackageGroup

Package grouping configuration.

interface PackageGroup {
  /** Group name */
  name: string

  /** Packages in group */
  packages: string[]

  /** Group-specific strategy */
  strategy?: UpdateStrategy

  /** Group labels */
  labels?: string[]

  /** Group reviewers */
  reviewers?: string[]

  /** Auto-merge for group */
  autoMerge?: boolean

  /** Group description */
  description?: string
}

WorkspaceConfig

Monorepo workspace configuration.

interface WorkspaceConfig {
  /** Auto-detect workspaces */
  autoDetect?: boolean

  /** Workspace patterns */
  patterns?: string[]

  /** Workspace-specific configs */
  configs?: Record<string, WorkspacePackageConfig>

  /** Coordination settings */
  coordination?: WorkspaceCoordination
}

interface WorkspacePackageConfig extends PackageConfig {
  /** Workspace path */
  path?: string

  /** Downstream workspaces */
  downstream?: string[]

  /** Requires testing */
  requiresTesting?: boolean
}

interface WorkspaceCoordination {
  /** Align shared dependencies */
  alignSharedDeps?: boolean

  /** Shared dependency groups */
  sharedGroups?: Record<string, SharedGroupConfig>

  /** Update ordering */
  updateOrder?: string[]
}

Pull Request Configuration

PullRequestConfig

Pull request generation settings.

interface PullRequestConfig {
  /** PR title template */
  title?: string

  /** PR body template */
  body?: string

  /** PR labels */
  labels?: LabelConfig

  /** Assignees */
  assignees?: AssigneeConfig

  /** Reviewers */
  reviewers?: ReviewerConfig

  /** Auto-merge settings */
  autoMerge?: AutoMergeConfig

  /** Draft PR settings */
  draft?: boolean

  /** Branch naming */
  branchNaming?: BranchNamingConfig
}

LabelConfig

Label configuration for pull requests.

interface LabelConfig {
  /** Static labels (always applied) */
  static?: string[]

  /** Dynamic labeling rules */
  dynamic?: DynamicLabelConfig

  /** Pattern-based labels */
  patterns?: Record<string, string[]>

  /** Conditional labels */
  conditions?: LabelCondition[]
}

interface DynamicLabelConfig {
  /** Enable dynamic labeling */
  enabled?: boolean

  /** Update type labels */
  updateType?: Record<UpdateStrategy, string>

  /** Ecosystem detection */
  ecosystems?: Record<string, string[]>

  /** Custom rules */
  rules?: LabelRule[]
}

interface LabelCondition {
  /** Condition function */
  when: (pr: PullRequestContext) => boolean

  /** Labels to apply */
  apply: string[]
}

interface LabelRule {
  /** Rule condition */
  condition: string

  /** Label to apply */
  label: string
}

AssigneeConfig

Assignee configuration.

interface AssigneeConfig {
  /** Static assignees */
  static?: string[]

  /** Dynamic assignment rules */
  rules?: AssigneeRule[]

  /** Maximum assignees */
  maxAssignees?: number

  /** Require assignee */
  requiresAssignee?: boolean
}

interface AssigneeRule {
  /** Rule condition */
  condition: string

  /** Assignees to assign */
  assignees: string[]
}

ReviewerConfig

Reviewer configuration.

interface ReviewerConfig {
  /** Default reviewers */
  default?: string[]

  /** Package-based reviewers */
  packageOwners?: Record<string, string[]>

  /** Team configuration */
  teams?: Record<string, TeamConfig>

  /** Review requirements */
  requirements?: ReviewRequirements

  /** Fallback reviewers */
  fallback?: string[]
}

interface TeamConfig {
  /** Team members */
  members: string[]

  /** Packages owned by team */
  packages: string[]

  /** Required reviews from team */
  requiredReviews?: number

  /** Auto-assign to team */
  autoAssign?: boolean
}

interface ReviewRequirements {
  /** Minimum required reviews */
  required?: number

  /** Count team reviews */
  teamReviews?: boolean

  /** Dismiss stale reviews */
  dismissStale?: boolean
}

AutoMergeConfig

Auto-merge configuration.

interface AutoMergeConfig {
  /** Enable auto-merge */
  enabled?: boolean

  /** Required status checks */
  requiredChecks?: string[]

  /** Merge method */
  method?: MergeMethod

  /** Conditions for auto-merge */
  conditions?: AutoMergeCondition[]

  /** Delay before merge */
  delay?: number
}

type MergeMethod = 'merge' | 'squash' | 'rebase'

interface AutoMergeCondition {
  /** Update type */
  updateType?: UpdateStrategy

  /** Package patterns */
  packages?: string[]

  /** Labels required */
  labels?: string[]

  /** Reviews required */
  reviews?: number
}

BranchNamingConfig

Branch naming configuration.

interface BranchNamingConfig {
  /** Branch prefix */
  prefix?: string

  /** Include update type */
  includeUpdateType?: boolean

  /** Include package count */
  includePackageCount?: boolean

  /** Custom template */
  template?: string

  /** Separator character */
  separator?: string
}

Schedule Configuration

ScheduleConfig

Scheduling and automation settings.

interface ScheduleConfig {
  /** Cron expression */
  cron?: string

  /** Timezone */
  timezone?: string

  /** Enable scheduling */
  enabled?: boolean

  /** Multiple schedules */
  schedules?: NamedSchedule[]

  /** Environment-based scheduling */
  environments?: Record<string, EnvironmentSchedule>

  /** Trigger-based updates */
  triggers?: TriggerConfig
}

interface NamedSchedule {
  /** Schedule name */
  name: string

  /** Cron expression */
  cron: string

  /** Schedule-specific strategy */
  strategy?: UpdateStrategy

  /** Schedule labels */
  labels?: string[]

  /** Schedule reviewers */
  reviewers?: string[]

  /** Auto-merge for schedule */
  autoMerge?: boolean
}

interface EnvironmentSchedule extends NamedSchedule {
  /** Environment name */
  environment?: string

  /** Require approval */
  requireApproval?: boolean
}

interface TriggerConfig {
  /** Security triggers */
  security?: SecurityTrigger

  /** Major release triggers */
  majorRelease?: MajorReleaseTrigger

  /** Batch threshold triggers */
  batchThreshold?: BatchThresholdTrigger
}

Release Notes Configuration

ReleaseNotesConfig

Release notes extraction and formatting.

interface ReleaseNotesConfig {
  /** Data sources */
  sources?: ReleaseNotesSource

  /** Content formatting */
  formatting?: ReleaseNotesFormatting

  /** Template configuration */
  template?: ReleaseNotesTemplate

  /** Aggregation settings */
  aggregation?: ReleaseNotesAggregation

  /** Caching configuration */
  caching?: CacheConfig
}

interface ReleaseNotesSource {
  /** GitHub releases */
  githubReleases?: GitHubReleasesConfig

  /** Changelog files */
  changelog?: ChangelogConfig

  /** NPM registry */
  npmRegistry?: NpmRegistryConfig

  /** Git commits */
  gitCommits?: GitCommitsConfig
}

interface ReleaseNotesFormatting {
  /** Markdown processing */
  markdown?: MarkdownConfig

  /** Content filters */
  filters?: ContentFilters

  /** Content enhancement */
  enhance?: ContentEnhancement
}

interface ReleaseNotesTemplate {
  /** Header template */
  header?: string

  /** Package section template */
  packageSection?: string

  /** Footer template */
  footer?: string

  /** Empty state message */
  empty?: string

  /** Error message */
  error?: string
}

Git Provider Configuration

GitProviderConfig

Git provider settings.

interface GitProviderConfig {
  /** Provider type */
  provider: GitProvider

  /** Provider-specific settings */
  github?: GitHubConfig
  gitlab?: GitLabConfig

  /** Authentication */
  auth?: AuthConfig

  /** API configuration */
  api?: ApiConfig
}

type GitProvider = 'github' | 'gitlab'

interface GitHubConfig {
  /** GitHub API URL */
  apiUrl?: string

  /** GitHub Enterprise URL */
  baseUrl?: string

  /** App ID for GitHub App */
  appId?: string

  /** Installation ID */
  installationId?: string

  /** Private key path */
  privateKeyPath?: string
}

interface GitLabConfig {
  /** GitLab instance URL */
  url?: string

  /** Project ID */
  projectId?: number

  /** Group ID */
  groupId?: number
}

interface AuthConfig {
  /** Personal access token */
  token?: string

  /** Token environment variable */
  tokenEnv?: string

  /** OAuth configuration */
  oauth?: OAuthConfig
}

interface ApiConfig {
  /** Request timeout */
  timeout?: number

  /** Retry attempts */
  retries?: number

  /** Rate limiting */
  rateLimit?: RateLimitConfig
}

Registry Configuration

RegistryConfig

Package registry settings.

interface RegistryConfig {
  /** Registry name */
  name: string

  /** Registry URL */
  url: string

  /** Authentication token */
  token?: string

  /** Scope for scoped registries */
  scope?: string

  /** Registry type */
  type?: RegistryType

  /** Cache configuration */
  cache?: CacheConfig
}

type RegistryType = 'npm' | 'github' | 'private'

Global Configuration

GlobalConfig

Global settings and defaults.

interface GlobalConfig {
  /** Verbose logging */
  verbose?: boolean

  /** Dry run mode */
  dryRun?: boolean

  /** Concurrency limit */
  concurrency?: number

  /** Timeout settings */
  timeout?: number

  /** Error handling */
  errorHandling?: ErrorHandlingConfig

  /** Performance settings */
  performance?: PerformanceConfig
}

interface ErrorHandlingConfig {
  /** Retry configuration */
  retry?: RetryConfig

  /** Fallback strategies */
  fallback?: FallbackConfig

  /** Error reporting */
  reporting?: ErrorReportingConfig
}

interface PerformanceConfig {
  /** Caching strategy */
  cache?: CacheStrategy

  /** Parallel processing */
  parallel?: ParallelConfig

  /** Memory management */
  memory?: MemoryConfig
}

Utility Types

PullRequestContext

Context object passed to conditional functions.

interface PullRequestContext {
  /** Packages being updated */
  packages: PackageUpdate[]

  /** Update type */
  updateType: UpdateStrategy

  /** Total package count */
  packageCount: number

  /** Has breaking changes */
  hasBreakingChanges: boolean

  /** Is security update */
  isSecurityUpdate: boolean

  /** Repository information */
  repository: RepositoryContext
}

interface PackageUpdate {
  /** Package name */
  name: string

  /** Current version */
  currentVersion: string

  /** Target version */
  targetVersion: string

  /** Update type */
  updateType: UpdateStrategy

  /** Has breaking changes */
  hasBreakingChanges: boolean

  /** Is dev dependency */
  isDevDependency: boolean

  /** Release notes */
  releaseNotes?: string
}

Helper Types

/** Deep partial type */
type DeepPartial<T> = {
  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P]
}

/** Configuration with environment overrides */
type ConfigWithEnv<T> = T & {
  env?: Record<string, DeepPartial<T>>
}

/** Conditional configuration */
type ConditionalConfig<T> = T | ((context: any) => T)

Configuration Validation

validateConfig

Validate configuration object.

import { assertValidConfig, formatConfigIssues, validateConfig } from '@buddysh/buddy'

/** Every problem found; an empty array means the config is valid. */
function validateConfig(config: BuddyConfig): ConfigIssue[]

/** Render issues as one human-readable block, one per line. */
function formatConfigIssues(issues: readonly ConfigIssue[]): string

/** Validate and throw a ConfigurationError listing every issue. */
function assertValidConfig(config: BuddyConfig): void

interface ConfigIssue {
  /** Dotted path to the offending key, e.g. `packages.groups[0].patterns` */
  path: string

  /** What is wrong and what was expected */
  message: string
}

const issues = validateConfig(config)
if (issues.length > 0)
  console.error(formatConfigIssues(issues))

Example Configurations

Basic Configuration

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

const config: BuddyConfig = {
  repository: {
    owner: 'myorg',
    name: 'myproject'
  },
  packages: {
    strategy: 'minor',
    ignore: ['react']
  },
  pullRequest: {
    labels: {
      static: ['dependencies']
    },
    reviewers: {
      default: ['team-lead']
    }
  }
}

export default config

Advanced Configuration

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

const config: BuddyConfig = {
  maxPRsPerRun: 5,

  packages: {
    strategy: 'minor',
    ignorePaths: ['examples/**', 'packages/test-*/**'],

    // Groups decide which packages share a pull request.
    groups: [
      {
        name: 'React Ecosystem',
        patterns: ['react', 'react-dom', '@types/react'],
        strategy: 'patch',
      },
    ],

    // Rules decide everything that varies per update: labels, reviewers,
    // auto-merge, release age, ordering and scheduling windows.
    rules: [
      {
        matchPackages: ['react', 'react-dom'],
        reviewers: ['frontend-team'],
        autoMerge: false,
      },
      {
        matchUpdateTypes: ['patch'],
        labels: ['patch-update'],
        prPriority: 10,
      },
      {
        matchUpdateTypes: ['major'],
        labels: ['major-update'],
        schedule: '0 0 * * 6,0', // weekends only
        prPriority: -10,
      },
    ],
  },

  pullRequest: {
    labels: ['dependencies'],
    reviewers: ['maintainer'],
    autoMerge: {
      enabled: true,
      strategy: 'squash',
      conditions: ['patch-only'],
      requireGreenCI: true,
    },
  },

  schedule: {
    cron: '0 2 * * *',
    timezone: 'UTC',
  },
}

export default config

Note the split between groups and rules. A PackageGroup has exactly three fields — name, patterns and strategy — and only decides batching. Anything conditional (labels, reviewers, assignees, auto-merge, release age, priority, scheduling windows) belongs in packages.rules. See scheduling for the full matcher and effect tables.

See Configuration Guide for detailed configuration examples and best practices.