Skip to content
/ pull-merge-bot Public

A Github tool that automates GitHub pull requests, issues, and code reviews across multiple accounts to simulate real-world collaboration and enhance contribution activity graphs.

www.npmjs.com/package/pull-merge-bot

License

MIT license
17 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

web2and3/pull-merge-bot

BranchesTags

Repository files navigation

🤖 Pull-Merge Bot

Node.js License Version GitHub npm

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

Authentication

To use the Pull Merge Bot, you need to generate two GitHub personal access tokens:

  1. Go to your GitHub account settings.
  2. Navigate to Developer settings > Personal access tokens.
  3. Click on Generate new token.
  4. Select the necessary scopes for your usage (e.g., repo, repo:status, public_repo, and Gist).
  5. Copy the tokens and set them in your environment variables as TOKEN_A and TOKEN_B.

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

  1. Check the documentation - README.md and CONFIGURATION.md
  2. Review examples - examples/basic-usage.js
  3. Use CLI help - pull-merge-bot --help
  4. 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

About

A Github tool that automates GitHub pull requests, issues, and code reviews across multiple accounts to simulate real-world collaboration and enhance contribution activity graphs.

www.npmjs.com/package/pull-merge-bot

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

17 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages