https://github.com/stacksjs/buddy-bot
🐶 Automated & optimized dependency updates for JavaScript & TypeScript projects. Like Renovate & Dependabot.
https://github.com/stacksjs/buddy-bot
automated dependabot dependency launchpad npm php renovate typescript updates zig
Last synced: 4 months ago
JSON representation
🐶 Automated & optimized dependency updates for JavaScript & TypeScript projects. Like Renovate & Dependabot.
- Host: GitHub
- URL: https://github.com/stacksjs/buddy-bot
- Owner: stacksjs
- License: mit
- Created: 2025-01-11T15:20:15.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-02-05T03:01:38.000Z (5 months ago)
- Last Synced: 2026-02-05T11:41:58.730Z (5 months ago)
- Topics: automated, dependabot, dependency, launchpad, npm, php, renovate, typescript, updates, zig
- Language: TypeScript
- Homepage: https://buddy.sh
- Size: 4.22 MB
- Stars: 8
- Watchers: 1
- Forks: 3
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
[![npm version][npm-version-src]][npm-version-href]
[![GitHub Actions][github-actions-src]][github-actions-href]
[](http://commitizen.github.io/cz-cli/)
# 🐶 Buddy Bot
> The fastest, most intelligent dependency management bot for modern JavaScript and TypeScript projects _(and PHP, Zig)_.
Buddy Bot is a lightning-fast alternative to Dependabot and Renovate, purpose-built for modern JavaScript, TypeScript, PHP, and Zig ecosystems. It intelligently scans your projects, detects outdated & deprecated dependencies across multiple package managers, and creates beautifully formatted pull requests with comprehensive changelogs and metadata.
## Features
### 🚀 **Performance & Speed**
- **Lightning Fast Execution**: _Built with Bun for maximum performance_
- **Intelligent Scanning**: _Uses `bun outdated` and GitHub releases API for accurate, real-time dependency detection_
- **Optimized CI/CD**: _Minimal resource usage with smart caching_
### 📦 **Universal Package Support**
- **Multi-Package Manager**: _Full support for Bun, npm, yarn, pnpm, Composer, Zig, pkgx & Launchpad_
- **GitHub Actions**: _Automatically updates workflow dependencies (`actions/checkout@v4`, etc.)_
- **Docker Images**: _Detects and updates Dockerfile base images and versions_
- **Zig Dependencies**: _Manages build.zig.zon dependencies with URL and hash tracking_
- **Lock File Awareness**: _Respects and updates all lock file formats_
### 🎯 **Smart Dependency Management**
- **Configurable Update Strategies**: _Choose from major, minor, patch, or all updates_
- **Flexible Package Grouping**: _Group related packages for cleaner, focused PRs_
- **Intelligent Conflict Detection**: _Prevents breaking changes with smart dependency analysis_
- **Security-First Updates**: _Prioritizes security patches and vulnerability fixes_
### 📊 **Rich Dashboard & Monitoring**
- **Dependency Dashboard**: _Centralized GitHub issue with complete dependency overview_
- **Interactive Rebase**: _One-click PR updates via checkbox interface_
- **Real-time Status Tracking**: _Live monitoring of all open PRs and pending updates_
- **Comprehensive Reporting**: _Detailed update summaries with confidence metrics_
### 🎨 **Beautiful Pull Requests**
- **Multi-Format Tables**: _Separate sections for npm, PHP/Composer, Zig, pkgx/Launchpad, and GitHub Actions_
- **Rich Metadata**: _Confidence badges, adoption metrics, age indicators, and download stats_
- **Detailed Changelogs**: _Automatic release notes and breaking change detection_
- **Professional Formatting**: _Clean, readable PR descriptions with proper categorization_
### ⚙️ **Developer Experience**
- **Zero Configuration**: _Works immediately with intelligent defaults_
- **Interactive Setup**: _Renovate-like guided configuration with validation_
- **Migration Tools**: _Seamless import from existing Renovate and Dependabot setups_
- **TypeScript Config**: _Full type safety with `buddy-bot.config.ts`_
### 🔌 **Extensible Integration**
- **Plugin Ecosystem**: _Built-in Slack, Discord, and Jira integrations_
- **Custom Hooks**: _Extensible system for organization-specific workflows_
- **CI/CD Ready**: _Pre-built GitHub Actions workflows for all use cases_
- **API Access**: _Programmatic control for advanced automation_
## Quick Start
```bash
# Install globally
bun add -g buddy-bot
# Interactive setup (recommended)
buddy-bot setup
# Non-interactive setup for CI/CD
buddy-bot setup --non-interactive
# Non-interactive with specific preset
buddy-bot setup --non-interactive --preset testing --verbose
# Or run directly for scanning only
buddy-bot scan
```
## Usage
### Interactive Setup
The easiest way to get started is with the interactive setup command:
```bash
buddy-bot setup
```
This comprehensive setup wizard will guide you through configuring automated dependency updates for your project in a Renovate-like experience.
### Non-Interactive Setup
For CI/CD pipelines and automated deployments, use the non-interactive mode:
```bash
# Basic non-interactive setup (uses defaults)
buddy-bot setup --non-interactive
# Specify preset and token setup
buddy-bot setup --non-interactive --preset testing --token-setup existing-secret --verbose
# Production setup with security focus
buddy-bot setup --non-interactive --preset security --token-setup existing-secret
```
**Available options:**
- `--non-interactive` - Skip all prompts, use defaults
- `--preset ` - Workflow preset: `standard`, `high-frequency`, `security`, `minimal`, `testing` (default: `standard`)
- `--token-setup ` - Token mode: `default-token`, `existing-secret`, `new-pat` (default: `default-token`)
The setup process includes:
**🔍 Pre-flight Validation**
- **Environment checks** - Validates git repository, Node.js/Bun installation
- **Conflict detection** - Scans for existing dependency management tools (Renovate, Dependabot)
- **Git configuration** - Ensures proper git user setup
- **GitHub CLI detection** - Suggests helpful tools for authentication
**📊 Smart Project Analysis**
- **Project type detection** - Identifies library, application, monorepo, or unknown projects
- **Package manager detection** - Detects Bun, npm, yarn, pnpm with lock file validation
- **Dependency ecosystem analysis** - Finds pkgx, Launchpad dependency files
- **GitHub Actions discovery** - Scans existing workflows for updates
- **Intelligent recommendations** - Suggests optimal setup based on project characteristics
**📈 Interactive Progress Tracking**
- **Visual progress bar** - Real-time completion percentage with progress indicators
- **Step-by-step guidance** - Clear indication of current and completed steps
- **Time tracking** - Setup duration monitoring
- **Recovery capabilities** - Resume from failures with detailed error reporting
**📋 Step 1: Configuration Migration & Discovery**
- **Tool Detection** - Automatically detects existing Renovate and Dependabot configurations
- **Seamless Migration** - Imports settings, schedules, package rules, and ignore patterns
- **Compatibility Analysis** - Identifies incompatible features and provides alternatives
- **Migration Report** - Detailed summary of migrated settings and confidence levels
**🔌 Step 2: Integration Discovery**
- **Plugin Discovery** - Automatically detects available integrations (Slack, Discord, Jira)
- **Environment Detection** - Scans for webhook URLs, API tokens, and configuration files
- **Plugin Loading** - Enables discovered integrations for setup completion notifications
- **Custom Plugins** - Supports custom plugin definitions in `.buddy/plugins/` directory
**🔍 Step 3: Repository Detection & Validation**
- Automatically detects your GitHub repository from git remote
- **API validation** - Tests repository access and permissions via GitHub API
- **Repository health checks** - Validates issues, permissions, and settings
- **Private repository support** - Enhanced validation for private repositories
**🔑 Step 4: Enhanced Token Setup**
- Guides you through creating a Personal Access Token (PAT)
- **Scope validation** - Explains required scopes (`repo`, `workflow`) with examples
- **Token testing** - Validates token permissions before proceeding
- Helps set up repository secrets for enhanced features
**🔧 Step 5: Repository Settings Validation**
- Walks you through GitHub Actions permissions configuration
- **Permission verification** - Tests workflow permissions in real-time
- **Organization settings** - Guidance for organization-level permissions
- Ensures proper workflow permissions for PR creation
**⚙️ Step 6: Intelligent Workflow Configuration**
Choose from several carefully crafted presets with smart recommendations:
- **Standard Setup (Recommended)** - Dashboard updates 3x/week, balanced dependency updates
- **High Frequency** - Check for updates multiple times per day
- **Security Focused** - Frequent patch updates with security-first approach
- **Minimal Updates** - Weekly checks, lower frequency
- **Development/Testing** - Manual triggers + frequent checks for testing
- **Custom Configuration** - Advanced schedule builder with cron preview
**📝 Step 7: Enhanced Configuration Generation**
- Creates `buddy-bot.config.json` with repository-specific settings
- **Project-aware defaults** - Configuration optimized for detected project type
- **Ecosystem integration** - Includes detected package managers and dependency files
- Includes sensible defaults and customization options
**🔄 Step 8: Workflow Generation & Validation**
- Generates three core GitHub Actions workflows:
- `buddy-dashboard.yml` - Dependency Dashboard Management
- `buddy-check.yml` - Auto-rebase PR checker
- `buddy-update.yml` - Scheduled dependency updates
- **YAML validation** - Ensures generated workflows are syntactically correct
- **Security best practices** - Validates token usage and permissions
- **Workflow testing** - Verifies generated workflows meet requirements
**🎯 Step 9: Comprehensive Validation & Instructions**
- **Setup verification** - Validates all generated files and configurations
- **Workflow testing** - Tests generated workflow syntax and requirements
- **Clear next steps** - Git commands and repository setup instructions
- **Documentation links** - Direct links to GitHub settings pages
- **Troubleshooting guide** - Common issues and solutions
**🔌 Step 10: Integration Notifications**
- **Plugin Execution** - Executes loaded integration hooks for setup completion
- **Slack Notifications** - Rich setup completion messages with repository details
- **Discord Embeds** - Colorful setup completion notifications with project information
- **Jira Tickets** - Automatic task creation for tracking setup completion
- **Custom Hooks** - Extensible system for organization-specific integrations
### Command Line Interface
```bash
# Setup commands
buddy setup # Interactive setup (recommended)
buddy setup --non-interactive # Non-interactive with defaults
buddy setup --non-interactive --preset testing --verbose
# Scan for dependency updates
buddy scan
buddy scan --verbose
# Check specific packages
buddy scan --packages "react,typescript,@types/node"
# Check packages with glob patterns
buddy scan --pattern "@types/*"
# Apply different update strategies
buddy scan --strategy minor
buddy scan --strategy patch
# Update dependencies and create PRs
buddy update --dry-run
buddy update
# Check for rebase requests and update PRs
buddy update-check
buddy update-check --dry-run
buddy update-check --verbose
# Get help
buddy help
```
### Configuration
Create a `buddy-bot.config.ts` file in your project root:
```typescript
import type { BuddyBotConfig } from 'buddy-bot'
const config: BuddyBotConfig = {
verbose: false,
// Repository settings for PR creation
repository: {
provider: 'github',
owner: 'your-org',
name: 'your-repo',
token: process.env.GITHUB_TOKEN,
baseBranch: 'main'
},
// Package update configuration
packages: {
strategy: 'all', // 'major' | 'minor' | 'patch' | 'all'
ignore: [
'legacy-package',
'@types/node' // Example ignores
],
groups: [
{
name: 'TypeScript Types',
patterns: ['@types/*'],
strategy: 'minor'
},
{
name: 'ESLint Ecosystem',
patterns: ['eslint*', '@typescript-eslint/*'],
strategy: 'patch'
}
]
},
// Pull request settings
pullRequest: {
titleFormat: 'chore(deps): {title}',
commitMessageFormat: 'chore(deps): {message}',
reviewers: ['maintainer1', 'maintainer2'],
labels: ['dependencies', 'automated'],
autoMerge: {
enabled: true,
strategy: 'squash', // 'merge', 'squash', or 'rebase'
conditions: ['patch-only'] // Only auto-merge patch updates
}
},
// Dependency dashboard settings
dashboard: {
enabled: true,
title: 'Dependency Dashboard',
pin: true,
labels: ['dependencies', 'dashboard'],
assignees: ['maintainer1'],
showOpenPRs: true,
showDetectedDependencies: true
}
}
export default config
```
## Configuration Migration
Buddy Bot can automatically migrate your existing dependency management configurations from Renovate and Dependabot, making the transition seamless.
### Supported Migration Sources
- **Renovate** - `renovate.json`, `.renovaterc`, package.json renovate config
- **Dependabot** - `.github/dependabot.yml`, `.github/dependabot.yaml`
### Migration Process
1. **Automatic Detection** - Scans for existing configuration files
2. **Smart Conversion** - Maps settings to Buddy Bot equivalents
3. **Compatibility Check** - Identifies unsupported features
4. **Migration Report** - Provides detailed conversion summary
```bash
# Migration happens automatically during setup
buddy-bot setup
# Or use programmatically
import { ConfigurationMigrator } from 'buddy-bot/setup'
const migrator = new ConfigurationMigrator()
const tools = await migrator.detectExistingTools()
const result = await migrator.migrateFromRenovate('renovate.json')
```
### Migrated Settings
| Renovate | Dependabot | Buddy Bot | Notes |
|----------|------------|-----------|-------|
| `schedule` | `schedule.interval` | Workflow presets | Mapped to Standard/High-Frequency/Minimal |
| `packageRules` | `ignore` | Package groups & ignore lists | Preserves grouping logic |
| `automerge` | N/A | Auto-merge settings | Includes strategy preferences |
| `assignees`/`reviewers` | N/A | PR configuration | Maintains team assignments |
## Integration Ecosystem
Buddy Bot includes an extensible plugin system that enables integrations with popular collaboration and project management tools.
### Built-in Integrations
#### Slack Integration
```bash
# Set environment variable
export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK"
# Or create config file
echo "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK" > .buddy/slack-webhook
```
**Features:**
- Rich setup completion notifications
- Repository and project details
- Error notifications for setup failures
- Configurable channel and username
#### Discord Integration
```bash
# Set environment variable
export DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/YOUR/DISCORD/WEBHOOK"
# Or create config file
echo "https://discord.com/api/webhooks/YOUR/DISCORD/WEBHOOK" > .buddy/discord-webhook
```
**Features:**
- Colorful embed notifications
- Project type and package manager details
- Timestamp tracking
- Setup completion confirmations
#### Jira Integration
```bash
# Set environment variables
export JIRA_API_TOKEN="your-jira-api-token"
export JIRA_BASE_URL="https://your-org.atlassian.net"
export JIRA_PROJECT_KEY="BUDDY" # Optional, defaults to BUDDY
```
**Features:**
- Automatic ticket creation for setup completion
- Repository and project context
- Configurable project keys
- Setup tracking and documentation
### Custom Plugins
Create custom integrations by defining plugins in `.buddy/plugins/`:
```jsonc
// .buddy/plugins/custom-integration.json
{
"name": "custom-integration",
"version": "1.0.0",
"enabled": true,
"triggers": [
{ "event": "setup_complete" },
{ "event": "validation_error" }
],
"hooks": [
{
"name": "custom-notification",
"priority": 10,
"async": true,
"handler": "// Custom JavaScript function"
}
],
"configuration": {
"webhook_url": "https://your-custom-webhook.com/notify",
"api_key": "your-api-key"
}
}
```
### Plugin Events
| Event | Description | Context |
|-------|-------------|---------|
| `pre_setup` | Before setup begins | Initial configuration |
| `post_setup` | After setup completes | Full setup context |
| `step_complete` | After each setup step | Step-specific progress |
| `validation_error` | When validation fails | Error details and recovery |
| `setup_complete` | Final setup completion | Complete project context |
### Programmatic Usage
```typescript
import { Buddy, ConfigManager } from 'buddy-bot'
// Load configuration
const config = await ConfigManager.loadConfig()
// Create Buddy instance
const buddy = new Buddy(config)
// Scan for updates
const scanResult = await buddy.scanForUpdates()
console.log(`Found ${scanResult.updates.length} updates`)
// Check specific packages
const updates = await buddy.checkPackages(['react', 'typescript'])
// Create pull requests
if (scanResult.updates.length > 0) {
await buddy.createPullRequests(scanResult)
}
// Create or update dependency dashboard
const dashboardIssue = await buddy.createOrUpdateDashboard()
console.log(`Dashboard updated: ${dashboardIssue.url}`)
```
## Dependency Dashboard
The dependency dashboard provides a centralized view of all your repository's dependencies and open pull requests in a single GitHub issue. Similar to Renovate's dependency dashboard, it gives you complete visibility into your dependency management.
### Key Features
- **📊 Single Overview**: All dependencies and PRs in one place
- **🔄 Interactive Controls**: Force retry/rebase PRs by checking boxes
- **📌 Pinnable Issue**: Keep dashboard at the top of your issues
- **🏷️ Smart Categorization**: Organized by npm, GitHub Actions, and dependency files
- **⚡ Auto-Updates**: Refreshes when dependencies change
## Rebase Functionality
Buddy Bot includes powerful rebase functionality that allows you to update existing pull requests with the latest dependency versions, similar to Renovate's rebase feature.
### How It Works
All Buddy Bot pull requests include a rebase checkbox at the bottom:
```markdown
---
- [ ] If you want to update/retry this PR, check this box
---
```
### Using the Rebase Feature
1. **Check the box**: In any Buddy Bot PR, check the rebase checkbox
2. **Automatic detection**: The rebase workflow runs every minute to detect checked boxes
3. **Updates applied**: The PR is automatically updated with the latest dependency versions
4. **Checkbox unchecked**: After successful rebase, the checkbox is automatically unchecked
### Rebase Command
You can also trigger rebase manually using the CLI:
```bash
# Check for PRs with rebase checkbox enabled and update them
buddy-bot update-check
# Dry run to see what would be rebased
buddy-bot update-check --dry-run
# With verbose output
buddy-bot update-check --verbose
```
### Automated Rebase Workflow
Buddy Bot includes a pre-built GitHub Actions workflow (`.github/workflows/buddy-check.yml`) that:
- **🕐 Runs every minute**: Automatically checks for rebase requests
- **🔍 Scans all PRs**: Finds Buddy Bot PRs with checked rebase boxes
- **📦 Updates dependencies**: Re-scans for latest versions and updates files
- **📝 Updates PR content**: Refreshes PR title, body, and file changes
- **✅ Maintains workflow files**: Updates GitHub Actions workflows (requires proper permissions)
### Workflow File Permissions
For the rebase functionality to update GitHub Actions workflow files, you need proper permissions:
#### Option 1: Personal Access Token (Recommended)
1. Create a [Personal Access Token](https://github.com/settings/tokens) with `repo` and `workflow` scopes
2. Add it as a repository secret named `BUDDY_BOT_TOKEN`
3. The workflow automatically uses it when available
#### Option 2: Default GitHub Token (Limited)
- Uses `GITHUB_TOKEN` with limited permissions
- Cannot update workflow files (`.github/workflows/*.yml`)
- Still updates package.json, lock files, and dependency files
### What Gets Updated During Rebase
- ✅ **package.json** - npm/yarn/pnpm dependencies
- ✅ **Lock files** - package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb
- ✅ **Dependency files** - deps.yaml, dependencies.yaml, pkgx.yaml
- ✅ **Zig manifests** - build.zig.zon with URL and hash updates
- ✅ **GitHub Actions** - workflow files (with proper permissions)
- ✅ **PR content** - Updated title, body, and metadata
### Quick Start
```bash
# Create basic dashboard
buddy-bot dashboard
# Create dashboard with custom title
buddy-bot dashboard --title "My Dependencies"
```
### Automated Dashboard Updates
Buddy Bot includes a pre-built GitHub workflow (`.github/workflows/buddy-dashboard.yml`) that automatically updates your dependency dashboard:
- **📅 Scheduled**: Runs Monday, Wednesday, Friday at 9 AM UTC
- **🖱️ Manual**: Trigger from Actions tab with custom options
- **📌 Auto-Pin**: Keeps dashboard pinned by default
- **🔍 Dry-Run**: Preview mode available
### Example Dashboard Output
The dashboard automatically organizes your dependencies and shows:
```markdown
## Open
The following updates have all been created. To force a retry/rebase of any, click on a checkbox below.
- [ ] [chore(deps): update react to v18](../pull/123) (`react`)
- [ ] [chore(deps): update @types/node](../pull/124) (`@types/node`)
## Detected dependencies
npm
package.json
- `react ^17.0.0`
- `typescript ^4.9.0`
- `@types/node ^18.0.0`
github-actions
.github/workflows/ci.yml
- `actions/checkout v3`
- `oven-sh/setup-bun v1`
```
## How It Works
Buddy Bot's intelligent workflow delivers unmatched speed and accuracy:
1. **⚡ Lightning-Fast Scanning**: Leverages `bun outdated` and parallel API calls for instant dependency analysis
2. **🔍 Universal Detection**: Automatically discovers and parses all dependency files across your entire project
3. **🧠 Smart Analysis**: Evaluates security implications, breaking changes, and compatibility before suggesting updates
4. **🎯 Intelligent Grouping**: Automatically clusters related packages to create focused, logical pull requests
5. **📊 Rich Context**: Fetches comprehensive metadata including adoption rates, confidence scores, and detailed changelogs
6. **✨ Professional PRs**: Generates beautifully formatted pull requests with actionable insights and clear upgrade paths
### Supported Dependency Files
Buddy automatically detects and updates the following dependency file formats:
#### Package Dependencies
- **package.json** - Traditional npm dependencies
- **composer.json** - PHP dependencies from Packagist
- **composer.lock** - PHP lock file with exact versions
- **build.zig.zon** - Zig package manager dependencies with URL and hash tracking
- **deps.yaml** / **deps.yml** - Launchpad/pkgx dependency declarations
- **dependencies.yaml** / **dependencies.yml** - Alternative dependency file format
- **pkgx.yaml** / **pkgx.yml** - pkgx-specific dependency files
- **.deps.yaml** / **.deps.yml** - Hidden dependency configuration files
#### GitHub Actions
- **.github/workflows/*.yml** - GitHub Actions workflow files
- **.github/workflows/*.yaml** - Alternative YAML extension
All dependency files are parsed using the `ts-pkgx` library to ensure compatibility with the pkgx registry ecosystem while maintaining support for tools like Launchpad that reuse the same registry format. GitHub Actions are detected by parsing `uses:` statements in workflow files and checking for updates via the GitHub releases API.
### Pull Request Format
Buddy generates comprehensive pull requests with **separate dependency tables** for each ecosystem:
#### 1. npm Dependencies
Full table with confidence badges, age, adoption metrics, and weekly download statistics:
```
| Package | Change | Age | Adoption | Passing | Confidence |
|---------|--------|-----|----------|---------|------------|
| lodash | ^4.17.20 → ^4.17.21 | 📅 | 📈 | ✅ | 🔒 |
```
#### 2. PHP/Composer Dependencies
Focused table for PHP packages from Packagist:
```
| Package | Change | File | Status |
|---------|--------|------|--------|
| laravel/framework | ^10.0.0 → ^10.16.0 | composer.json | ✅ Available |
| phpunit/phpunit | ^10.0.0 → ^10.3.0 | composer.json | ✅ Available |
```
#### 3. Zig Dependencies
Focused table for Zig packages with repository links and update types:
```
| Package | Change | Type | File |
|---------|--------|------|------|
| httpz | 0.5.0 → 0.6.0 | 🟡 minor | build.zig.zon |
```
#### 4. Launchpad/pkgx Dependencies
Simplified table focusing on package updates and file locations:
```
| Package | Change | File | Status |
|---------|--------|------|--------|
| bun.com | ^1.2.16 → ^1.2.19 | deps.yaml | ✅ Available |
```
#### 5. GitHub Actions
Workflow automation updates with direct links to repositories:
```
| Action | Change | File | Status |
|--------|--------|------|--------|
| actions/checkout | v4 → v4.2.2 | ci.yml | ✅ Available |
| oven-sh/setup-bun | v2 → v2.0.2 | release.yml | ✅ Available |
```
Each table is followed by detailed release notes, changelogs, and package statistics tailored to the dependency type.
## Update Strategies
- **`all`**: Update all dependencies regardless of semver impact
- **`major`**: Only major version updates
- **`minor`**: Major and minor updates (no patch-only)
- **`patch`**: All updates (major, minor, and patch)
## Auto-Merge Configuration
Buddy supports configurable auto-merge for pull requests to reduce manual overhead:
```typescript
const config: BuddyBotConfig = {
pullRequest: {
autoMerge: {
enabled: true,
strategy: 'squash', // 'merge', 'squash', or 'rebase'
conditions: ['patch-only'] // Optional: restrict to specific update types
}
}
}
```
### Auto-Merge Strategies
- **`squash`**: Squash commits and merge _(recommended for clean history)_
- **`merge`**: Create a merge commit _(preserves individual commits)_
- **`rebase`**: Rebase and merge _(linear history without merge commits)_
### Auto-Merge Conditions
- **`patch-only`**: Only auto-merge patch version updates _(safest)_
- **No conditions**: Auto-merge all updates _(use with caution)_
### Workflow-Specific Auto-Merge
Each preset configures auto-merge appropriately:
- **High Frequency Updates**: Auto-merge patch updates only _(6AM, 12PM, 6PM)_, manual review for minor updates _(12AM)_
- **Security Focused**: Auto-merge security patches every 6 hours
- **Standard Project**: Auto-merge daily patches, manual review for weekly/monthly updates
- **Development/Testing**: No auto-merge, dry-run by default, enhanced testing features.
## Development & Testing
The **Development/Testing** preset is specifically designed for testing and development environments:
### Features
- **⏰ Every 5 minutes**: Automated runs for rapid testing cycles
- **🖱️ Manual triggers**: Full control via GitHub Actions UI
- **🔍 Dry run by default**: Safe testing without making changes
- **📝 Verbose logging**: Detailed output for debugging
- **📦 Package-specific testing**: Test updates for specific packages
- **📊 Enhanced summaries**: Detailed test reports with context
### Manual Trigger Options
When running manually, you can customize:
- **Update strategy**: Choose patch, minor, major, or all updates
- **Dry run mode**: Preview changes without applying them
- **Specific packages**: Test updates for particular packages only
- **Verbose logging**: Control output detail level
### Perfect For
- 🧪 Testing new configurations
- 🔧 Debugging dependency issues
- 📈 Monitoring update frequency
- 🚀 Validating workflow changes
- 📋 Learning how Buddy Bot works
## Package Grouping
Group related packages to create cleaner, more focused pull requests:
```typescript
{
groups: [
{
name: 'React Ecosystem',
patterns: ['react*', '@types/react*'],
strategy: 'minor'
},
{
name: 'Development Tools',
patterns: ['eslint*', 'prettier*', '@typescript-eslint/*'],
strategy: 'patch'
}
]
}
```
## Example Output
When Buddy finds updates, it creates PRs like:
```
chore(deps): update all non-major dependencies
This PR contains the following updates:
| Package | Change | Age | Adoption | Passing | Confidence |
|---|---|---|---|---|---|
| [typescript](https://www.typescriptlang.org/) | `^5.8.2` -> `^5.8.3` | [](https://docs.renovatebot.com/merge-confidence/) | [](https://docs.renovatebot.com/merge-confidence/) | [](https://docs.renovatebot.com/merge-confidence/) | [](https://docs.renovatebot.com/merge-confidence/) |
---
### Release Notes
microsoft/TypeScript (typescript)
### [`v5.8.3`](https://github.com/microsoft/TypeScript/releases/tag/v5.8.3)
[Compare Source](https://github.com/microsoft/TypeScript/compare/v5.8.2...v5.8.3)
##### Bug Fixes
- Fix issue with module resolution
- Improve error messages
---
### Configuration
📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined).
🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied.
♻ **Rebasing**: Whenever PR is behind base branch, or you tick the rebase/retry checkbox.
🔕 **Ignore**: Close this PR and you won't be reminded about this update again.
---
- [ ] If you want to update/retry this PR, check this box
---
This PR was generated by [Buddy](https://github.com/stacksjs/buddy-bot).
```
## Why Choose Buddy Bot?
| Feature | Buddy Bot | Dependabot | Renovate |
|---------|-----------|------------|----------|
| **Performance** | ⚡ Lightning fast (Bun-native) | 🐌 | 🐌 |
| **Package Ecosystem** | 🌟 Universal (8+ managers) | 📦 Limited scope | 📦 Limited scope |
| **Setup Experience** | 🎯 Interactive + Zero config | ✅ Simple | ❌ Complex configuration |
| **Docker Support** | ✅ Full Dockerfile updates | ❌ No support | ✅ Basic support |
| **Configuration** | 🔧 TypeScript + multiple formats | 📝 YAML only | 📝 JSON/JS only |
| **Package Grouping** | 🎨 Intelligent + flexible | 📋 Basic grouping | 🔧 Advanced but complex |
| **Dashboard** | 📊 Rich interactive dashboard | ❌ No dashboard | 📊 Basic dashboard |
| **Migration Tools** | 🔄 Automated import | ❌ Manual migration | ❌ Manual migration |
| **Self-hosting** | ✅ Full control | ❌ GitHub-only | ✅ Complex setup |
| **Plugin System** | 🔌 Extensible ecosystem | ❌ Limited | 🔌 Advanced but complex |
## CI/CD Integration
### GitHub Actions
Buddy includes powerful GitHub Actions workflow templates for different automation strategies:
```yaml
# Basic dependency updates (generated by setup)
name: Buddy Update
on:
schedule:
- cron: '0 */2 * * *' # Every 2 hours
workflow_dispatch:
inputs:
strategy:
description: Update strategy
required: false
default: patch
dry_run:
description: Dry run (preview only)
required: false
default: true
type: boolean
jobs:
dependency-update:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: oven-sh/setup-bun@v2
- run: bun install
- run: bunx buddy-bot scan --strategy ${{ github.event.inputs.strategy || 'patch' }} --verbose
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- if: ${{ github.event.inputs.dry_run != 'true' }}
run: bunx buddy-bot update --strategy ${{ github.event.inputs.strategy || 'patch' }} --verbose
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
**🚀 Generate Advanced Workflows:**
```bash
# Generate comprehensive GitHub Actions workflows
buddy generate-workflows
# This creates:
# - buddy-comprehensive.yml (multi-strategy scheduling)
# - dependency-updates-daily.yml (patch updates)
# - dependency-updates-weekly.yml (minor updates)
# - dependency-updates-monthly.yml (major updates)
# - buddy-monorepo.yml (monorepo support)
# - buddy-docker.yml (Docker-based)
```
**🔥 Comprehensive Multi-Strategy Workflow:**
The updated workflow system automatically:
- **Every 2 hours**: All configured strategies with dry-run by default
- **Manual trigger**: Any strategy with configurable dry-run option
- **Enhanced testing**: Comprehensive validation and summaries
- **Failure handling**: Auto-creates GitHub issues
- **Smart summaries**: Rich GitHub Actions summaries
- **Flexible scheduling**: Consistent 2-hour intervals for all presets
### GitHub Actions Permissions Setup
⚠️ **Important**: For Buddy to create pull requests in GitHub Actions workflows, you need to enable the proper permissions:
#### Repository Settings
1. Go to your repository **Settings** → **Actions** → **General**
2. Under **"Workflow permissions"**, select **"Read and write permissions"**
3. ✅ Check **"Allow GitHub Actions to create and approve pull requests"**
4. Click **"Save"**
#### Organization Settings (if applicable)
If your repository is part of an organization, you may also need to enable organization-level permissions:
1. Go to your organization **Settings** → **Actions** → **General**
2. Configure the same permissions as above
#### Quick Setup Command
```bash
# Open GitHub settings pages directly
buddy open-settings
# Or manually visit:
# Repository: https://github.com/YOUR_ORG/YOUR_REPO/settings/actions
# Organization: https://github.com/organizations/YOUR_ORG/settings/actions
```
#### Troubleshooting
If you see errors like:
- `GitHub Actions is not permitted to create or approve pull requests`
- `GraphQL: GitHub Actions is not permitted to create or approve pull requests (createPullRequest)`
This indicates the permissions above need to be enabled. Both GitHub CLI and REST API methods require these permissions to create PRs from workflows.
For more details, see the [GitHub documentation on managing GitHub Actions settings](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#preventing-github-actions-from-creating-or-approving-pull-requests).
## Testing
```bash
bun test
```
## Build From Source
```bash
bun run build
```
## Changelog
Please see our [releases](https://github.com/stacksjs/stacks/releases) page for more information on what has changed recently.
## Contributing
Please see the [Contributing Guide](https://github.com/stacksjs/contributing) for details.
## Community
For help, discussion about best practices, or any other conversation that would benefit from being searchable:
[Discussions on GitHub](https://github.com/stacksjs/stacks/discussions)
For casual chit-chat with others using this package:
[Join the Stacks Discord Server](https://discord.gg/stacksjs)
## Postcardware
“Software that is free, but hopes for a postcard.” We love receiving postcards from around the world showing where Stacks is being used! We showcase them on our website too.
Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎
## Sponsors
We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.
- [JetBrains](https://www.jetbrains.com/)
- [The Solana Foundation](https://solana.com/)
## Credits
- [Renovatebot](https://renovatebot.com/)
- [Dependabot](https://dependabot.com/)
- [Chris Breuer](https://github.com/chrisbbreuer)
- [All Contributors](../../contributors)
And a special thanks to [Dan Scanlon](https://twitter.com/danscan) for donating the `stacks` name on npm ✨
## License
The MIT License (MIT). Please see [LICENSE](LICENSE.md) for more information.
Made with 💙
[npm-version-src]: https://img.shields.io/npm/v/buddy-bot?style=flat-square
[npm-version-href]: https://npmjs.com/package/buddy-bot
[github-actions-src]: https://img.shields.io/github/actions/workflow/status/stacksjs/buddy/ci.yml?style=flat-square&branch=main
[github-actions-href]: https://github.com/stacksjs/buddy/actions?query=workflow%3Aci