🤖 Follower Bot

An automated bot for following and reciprocating follows with GitHub users.

中文 | English

🌟 Features

1. Full Automation - No manual intervention required.
2. State Management - Uses persistent storage to ensure operations resume after restarts.
3. Multiple Deployment Options - Supports Windows service, Docker container, and more.

🎯 Function

1. Sync all followers/following.
2. Auto follow user who follow you.
3. Auto unfollow user who unfollow you.
4. Condition based auto unfollow/follow.
5. Email notifications for statistics and exception information.

🚀 Usage

🔧 Prerequisites

Warning

♻ Do not set the request frequency too high when modifying configurations. Excessive requests may trigger GitHub restrictions (⛔ including potential IP blocking, rate limiting, or account suspension. Proceed with caution!!!).

1. Clone the repository.
2. Generate a GitHub personal access token with at least the user:follow scope. See: Managing Personal Access Tokens.
3. Save the token to the GITHUB_TOKEN variable in the .env.local file.
4. Modify other configurations in the .env file as needed.
5. Modify the bot configurations in the bots.yaml file as needed.

📦 Data Storage

Modify the DATABASE.URL configuration item in the .env file to support the following databases:

🐬 MySQL (Recommended)

# Install dependencies
rye add pymysql

DATABASE.URL = mysql+pymysql://username:password@localhost/follower_bot

🪶 SQLite (Default)

DATABASE.URL = sqlite:///data/store.db

📬 Email Notifications (Optional)

Configure the relevant settings in the .env.local file to enable the email notification feature.

# Email configuration
# SMTP server
EMAIL.SMTP_SERVER = smtp.gmail.com
# SMTP port
EMAIL.SMTP_PORT = 587
# SMTP username
EMAIL.SMTP_USERNAME = "username"
# SMTP password
EMAIL.SMTP_PASSWORD = "password"
# Sender email address
EMAIL.SENDER_EMAIL = "sender@example.com"
# List of recipient email addresses
EMAIL.RECIPIENT_EMAILS = ["recipient@example.com"]

🏃‍♂️ Run the Bot

🪟 Run on Windows

Note

If using a custom Python environment, update the <executable/> path in follower-bot-service.xml.

# Create a virtual environment and install dependencies
rye sync
# WinSW config reference: https://github.com/winsw/winsw/blob/v3/docs/xml-config-file.md
# Register as a Windows service
follower-bot-service.exe install
# Start the service
follower-bot-service.exe start
# Stop the service
follower-bot-service.exe stop
# Uninstall the service
follower-bot-service.exe uninstall

🐋 Run with Docker

# Build the Docker image
docker build -t follower-bot .
# Run the Docker container
docker run -d --name follower-bot -v "logs:/app/logs" -v "data:/app/data" follower-bot
# Stop the container
docker stop follower-bot

🧪 Development and Debugging

Debugging in a virtual environment (recommended):

# Install dependencies
rye sync
# Run/Debug the bot
rye run start [-h]

Debugging in a local environment:

# Install dependencies
pip install --no-cache -r requirements.lock
# Run/Debug the bot
python -m follower_bot.bot [-h]

📦 Related Tools

• Rye: Python environment manager
• WinSW: Windows service manager
• Github API: GitHub API reference
• pydantic: Python data validation
• pydantic-settings: Settings management for Pydantic
• loguru: Python logging library
• loguru-config: Configuration for loguru
• requests: HTTP library for Python
• rate-keeper: API Rate Keeper Decorator
• apscheduler: Task scheduling library for Python
• sqlmodel: SQL and ORM library for Python
• pyyaml: YAML parser and emitter for Python

🔗 References

OfficialCodeVoyage/Github_Automation_Follower_Bot