📘 GitHub Contribution Bot – User Guide

✅ Getting Started

This bot helps automate GitHub commits to maintain your contribution graph and simulate human-like activity.

• Requires a GitHub Personal Access Token (classic)
• Use with your own public repositories
• Commits to any file path you choose (e.g., log.md)

🔑 How to Create a GitHub Personal Access Token (PAT)

To use this bot, you need a GitHub Personal Access Token with the necessary permissions. Follow these steps:

1. Go to your GitHub settings: Navigate to GitHub Personal Access Tokens.
2. Click on "Generate new token (classic)".
3. Give your token a descriptive name (e.g., "GitHub Bot Token").
4. Set an expiration date (e.g., 90 days or 1 year) or "No expiration" (use with caution).
5. Under "Select scopes", **check the repo checkbox**. For fetching your real contribution heatmap, you also need to check read:user.
6. Click "Generate token" at the bottom of the page.
7. **IMPORTANT:** Copy the generated token immediately. You will not be able to see it again! Store it securely.
8. Paste this token into the "GitHub Personal Access Token (PAT)" field in the bot's "Main Controls" tab.

For more details, refer to GitHub's official documentation on managing personal access tokens.

ℹ️ Token Scopes Explained

GitHub Personal Access Tokens require specific permissions, called "scopes," to perform actions on your behalf. Here's what the bot needs:

• repo: This scope grants the bot full control over your private repositories. It is essential for the bot to create, update, and delete files (i.e., make commits) in the repositories you select. Without this, the bot cannot commit.
• read:user: This scope allows the bot to read your user profile data. It is specifically used to fetch your public GitHub activity events for displaying your "Real GitHub Contribution Heatmap." Without this, the heatmap feature might not work correctly.

Providing only the necessary scopes is a security best practice to limit the bot's access to your GitHub account.

✨ How to Provide Gemini API Key

The bot can generate smart commit messages using the Gemini API. To enable this feature, you need to provide your Gemini API Key:

1. Obtain your Gemini API Key from the Google AI Studio or Google Cloud Console.
2. In the bot's "Main Controls" tab, locate the "Gemini API Key (for Smart Commit Messages)" input field.
3. Paste your Gemini API Key into this field.
4. The key will be automatically saved to your browser's local storage for future use.

Ensure your API key is kept confidential and is not shared publicly.

🛠️ How to Use

1. Paste your GitHub token (with repo and read:user scopes)
2. Select one or more of your repositories
3. Set the file path and branch (default: main)
4. Optionally provide your Gemini API Key for smart commit messages.
5. Use Manual, Auto Commit, or Safe Mode options.
6. Explore the new features like Smart Rotation, Commit Preview, and Stats Panel.

🔄 Smart Rotation

Smart Rotation is a feature designed to distribute automated commits more evenly across multiple selected repositories.

• When enabled, the bot will cycle through your selected repositories in a round-robin fashion for each subsequent auto-commit.
• This helps create a more natural and diversified contribution graph across your projects.
• You can enable or disable this feature using the "Enable Smart Rotation (Round-Robin Repos)" checkbox in the "Main Controls" tab.

🧠 Safe Mode Explained

Safe Mode simulates real human behavior by:

• ⏱️ Adding random delays between commits (20–30 minutes)
• 🔀 Rotating across multiple repos
• 🧾 Generating natural, varied commit messages
• 💤 Occasionally skipping commits to avoid bot detection

Enable this feature using the "Enable Safe Mode (Human-like Behavior)" checkbox in the "Main Controls" tab for a more organic contribution pattern.

👀 Commit Preview Modal

The Commit Preview Modal provides a confirmation step before a commit is actually made, whether manually or automatically.

• Why it's useful:
  • Avoids sending incorrect or duplicate messages.
  • Allows you to edit the message or content, making the commit feel more personal, especially in Safe Mode.
  • Provides transparency on what's going on behind-the-scenes.
• What it shows:
  • Commit message
  • File path
  • Content snippet
  • (Optional) A countdown timer for auto-commits.
• You can enable or disable this feature using the "Enable Commit Preview" checkbox in the "Main Controls" tab.

📈 Stats Panel

The Stats Panel provides insights into your bot's usage and commit activity.

• Total Commits: The total number of commits made by the bot.
• Safe Mode Commits: The number and percentage of commits made while Safe Mode was enabled.
• First Commit Date: The date of the very first commit recorded by the bot.
• Average Interval: The average time between commits.
• Top Used Repo: The repository where the most commits have been made.

You can access this panel via the "Stats" tab and reset the statistics at any time using the "Reset Stats" button.

⚠️ What To Do

• ✅ Use your own repos
• ✅ Let commits spread over time
• ✅ Commit real or test data, not junk
• ✅ Keep messages unique or random

🚫 What Not To Do

• ❌ Don’t spam commits every few seconds
• ❌ Don’t push to other users’ repos
• ❌ Don’t use stolen tokens or fake accounts
• ❌ Don’t game contribution stats dishonestly

🧪 Pro Tips

• 📱 Install the app as a PWA
• 🧭 Use multi-repo rotation for realism
• 📊 Use the real heatmap preview to track your growth
• 🧠 Let Safe Mode handle randomness
• 👀 Enable Commit Preview for transparency and control.
• 📈 Monitor your bot's activity with the Stats Panel.

💻 Advanced Usage (Dev Mode)

Trigger Safe Mode loop manually:

safeAutoCommitLoop(["CryptoExplor/test-repo", "CryptoExplor/logs"]);

Stop loop manually:

safeModeEnabled = false;

🚫 Can You Get Banned by GitHub for Using This Bot?

🔍 Short Answer: Very Unlikely — If Used Responsibly

Your script does not break GitHub’s Terms of Service as long as:

• ✅ You’re committing to your own repositories
• ✅ You’re not automating spam or harmful content
• ✅ You’re not trying to manipulate public-facing metrics dishonestly (e.g., for applying to jobs)
• ✅ You’re not doing this at mass scale across multiple accounts

🛑 What Might Trigger a Ban or Flag?

💡 Best Practices to Stay Safe

✅ Real-World Example

Many devs use tools like:

• GitHub Readme Stats
• GitHub Activity Faker
• …and none of them get banned, because they’re used on personal accounts in moderation.

🔐 Bonus Tip: Keep Your Token Safe

• Never commit your token to GitHub
• Use Classic PAT with only repo scope
• Store in localStorage or environment only

✅ TL;DR:

Your current bot is:

• Safe for personal use
• Okay for automation
• Not spammy or malicious
• Not a ToS violation

Just don’t abuse it, and you’re 💯 safe.