pull-merge-bot

v2.0.1

Published

10 months ago

🤖 Automated GitHub bot that creates pull requests, performs code reviews, and creates issues with configurable random chance. Perfect for increasing GitHub contribution graphs and maintaining repository activity.

🤖 Pull-Merge Bot

Automated GitHub bot that creates pull requests, performs code reviews, and creates issues with configurable random chance. Perfect for increasing GitHub contribution graphs and maintaining repository activity.

🚀 Quick Start

Install as npm package

npm install pull-merge-bot

Use in your code

const { PullMergeBot } = require("pull-merge-bot");

const bot = new PullMergeBot({
  tokenA: "your_github_token_a",
  tokenB: "your_github_token_b",
  repoOwner: "your_username",
  repoName: "your-repo",
  forkOwner: "your_username",
  createIssue: true,
  enableCodeReview: true,
  randomChancePercentage: 30,
});

// Run the bot
const success = await bot.run();

Use as CLI tool

# Install globally
npm install -g pull-merge-bot

# Run with configuration
pull-merge-bot run

# Show current config
pull-merge-bot config

# Setup wizard
pull-merge-bot setup

✨ Features

🚀 Core Features

Automated PR Creation: Creates pull requests from specified branches
Smart Code Review: Performs detailed code analysis with file-by-file review
Issue Management: Creates issues with customizable types and content
Random Chance System: Configurable probability for realistic activity patterns
Dual Account Support: Separate roles for invited user and repository owner

🎯 Advanced Features

Contribution Optimization: Increases GitHub contribution graphs naturally
File Analysis: Reviews JavaScript, TypeScript, and Markdown files
Quality Metrics: Tracks code quality and provides smart suggestions
Separated Roles: Review comments from invited account, approval from owner
Configurable Activity: Set custom probability for features (1-100%)

🎲 Random Chance System

The bot uses a configurable random chance for realistic activity patterns:

Issue Creation: Triggers based on randomChancePercentage when enabled
Code Review: Triggers based on randomChancePercentage when enabled
Natural Patterns: Makes activity look organic and human-like
Predictable: Same PR will have consistent behavior

🛠️ Installation & Usage

Method 1: npm package (Recommended)

Install

npm install pull-merge-bot

Basic Usage

const { PullMergeBot } = require("pull-merge-bot");

const bot = new PullMergeBot({
  tokenA: process.env.TOKEN_A,
  tokenB: process.env.TOKEN_B,
  repoOwner: "yourusername",
  repoName: "your-repo",
  forkOwner: "yourusername",
});

// Run the bot
bot.run().then((success) => {
  if (success) {
    console.log("✅ Bot completed successfully!");
  }
});

Advanced Configuration

const bot = new PullMergeBot({
  // Required
  tokenA: "ghp_your_token_a",
  tokenB: "ghp_your_token_b",
  repoOwner: "yourusername",
  repoName: "your-repo",
  forkOwner: "yourusername",

  // Optional
  branchName: "feature-branch",
  createIssue: true,
  issueType: "enhancement",
  issueTitle: "Custom Issue Title",
  issueBody: "Custom issue description",
  enableCodeReview: true,
  randomChancePercentage: 50,
});

Method 2: CLI Tool

Install globally

npm install -g pull-merge-bot

Run with environment variables

# Set environment variables in .env file
export TOKEN_A=your_token_a
export TOKEN_B=your_token_b
export REPO_OWNER=yourusername
export REPO_NAME=your-repo
export FORK_OWNER=yourusername

# Run the bot
pull-merge-bot run

Run with command line options

pull-merge-bot run \
  --token-a your_token_a \
  --token-b your_token_b \
  --repo-owner yourusername \
  --repo-name your-repo \
  --fork-owner yourusername \
  --create-issue \
  --enable-code-review \
  --random-chance 50

CLI Commands

# Show help
pull-merge-bot --help

# Show current configuration
pull-merge-bot config

# Setup wizard
pull-merge-bot setup

# Run with specific options
pull-merge-bot run --create-issue --enable-code-review

🔧 Configuration

Configuration Options

| Option | Type | Required | Default | Description | | ------------------------ | ------- | -------- | ---------------------------- | ------------------------------------ | | tokenA | string | ✅ | - | GitHub token for invited user | | tokenB | string | ✅ | - | GitHub token for repository owner | | repoOwner | string | ✅ | - | Repository owner username | | repoName | string | ✅ | - | Repository name | | forkOwner | string | ✅ | - | Invited user username | | branchName | string | ❌ | "jonny" | Branch to work with | | createIssue | boolean | ❌ | false | Enable issue creation | | issueType | string | ❌ | "enhancement" | Issue type (bug/feature/enhancement) | | issueTitle | string | ❌ | "Automated Issue Creation" | Custom issue title | | issueBody | string | ❌ | Generic message | Custom issue description | | enableCodeReview | boolean | ❌ | false | Enable code review | | randomChancePercentage | number | ❌ | 30 | Probability percentage (1-100) |

Environment Variables

Create a .env file:

# Required
TOKEN_A=your_github_token_a
TOKEN_B=your_github_token_b
REPO_OWNER=your_username
REPO_NAME=your_repo
FORK_OWNER=your_username

# Optional
BRANCH_NAME=feature-branch
CREATE_ISSUE=true
ISSUE_TYPE=enhancement
ENABLE_CODE_REVIEW=true
RANDOM_CHANCE_PERCENTAGE=30

📊 Examples

Example 1: Minimal Setup

const { PullMergeBot } = require("pull-merge-bot");

const bot = new PullMergeBot({
  tokenA: process.env.TOKEN_A,
  tokenB: process.env.TOKEN_B,
  repoOwner: "yourusername",
  repoName: "your-repo",
  forkOwner: "yourusername",
});

await bot.run();

Example 2: Full Features

const bot = new PullMergeBot({
  tokenA: "ghp_your_token_a",
  tokenB: "ghp_your_token_b",
  repoOwner: "yourusername",
  repoName: "your-repo",
  forkOwner: "yourusername",
  branchName: "enhancement-branch",
  createIssue: true,
  issueType: "feature",
  issueTitle: "New Feature Request",
  issueBody: "Requesting new feature implementation",
  enableCodeReview: true,
  randomChancePercentage: 50,
});

await bot.run();

Example 3: Factory Function

const { createBot } = require("pull-merge-bot");

const bot = createBot({
  tokenA: process.env.TOKEN_A,
  tokenB: process.env.TOKEN_B,
  repoOwner: process.env.REPO_OWNER,
  repoName: process.env.REPO_NAME,
  forkOwner: process.env.FORK_OWNER,
  createIssue: true,
  enableCodeReview: true,
});

await bot.run();

🎯 Use Cases

Low Activity (10-20%)

randomChancePercentage: 10;

Perfect for maintaining minimal activity without being too obvious.

Balanced Activity (30-40%)

randomChancePercentage: 30;

Default setting for natural, balanced contribution patterns.

High Activity (50-70%)

randomChancePercentage: 50;

For more frequent contributions and active repository engagement.

Maximum Activity (80-100%)

randomChancePercentage: 100;

For maximum contribution activity and repository maintenance.

🔍 Code Review Features

File Analysis: Reviews JavaScript, TypeScript, and Markdown files
Change Metrics: Tracks additions, deletions, and total changes
Smart Suggestions: Provides context-aware recommendations
Documentation Review: Special handling for README and documentation files
Code Quality Checks: Identifies large changes and suggests testing
Separated Roles: Account A reviews, Account B approves

🎲 Random Chance Examples

When Features Are Triggered

🎲 Random chance triggered: Creating issue...
🎲 Random chance triggered: Performing code review...

When Features Are Skipped

🎲 Random chance not triggered: Skipping issue creation
🎲 Random chance not triggered: Skipping code review

📈 Benefits

For Developers

Automated Workflow: Reduces manual repository maintenance by 90%
Contribution Enhancement: Naturally increases GitHub activity
Learning Tool: Great for understanding GitHub API and automation
Customizable: Flexible configuration for different needs

For Repositories

Active Maintenance: Keeps repositories engaging and active
Quality Reviews: Automated code review with detailed analysis
Issue Tracking: Automated issue creation and management
Natural Patterns: Realistic activity that doesn't look automated

For Teams

Collaboration: Supports multiple account workflows
Role Separation: Clear separation of responsibilities
Audit Trail: Detailed logging and activity tracking
Scalable: Easy to configure for multiple repositories

🛠️ Development

Clone and Install

git clone https://github.com/yourusername/pull-merge-bot.git
cd pull-merge-bot
npm install

Build

npm run build

Development

npm run dev

Test

npm test

📞 Support

Documentation

README.md: This file with comprehensive examples
CONFIGURATION.md: Detailed configuration guide
PROJECT_INDEX.md: Complete project overview
examples/: Code examples and usage patterns

Getting Help

Check the documentation - README.md and CONFIGURATION.md
Review examples - examples/basic-usage.js
Use CLI help - pull-merge-bot --help
Open an issue - GitHub issues for bugs and questions

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with Octokit for GitHub API integration
Uses dotenv for environment management
CLI built with Commander.js
Inspired by the need for automated repository maintenance

⭐ If this project helps you, please give it a star! ⭐

🔗 GitHub: https://github.com/yourusername/pull-merge-bot

📦 npm: https://www.npmjs.com/package/pull-merge-bot