🌐 GitHub Orbit

A self-hosted GitHub bot that automatically follows back your followers and unfollows users who don't follow you back — with smart bot filtering and rate limiting built in.

---

✨ What It Does

Job	Schedule	Action
Follow	Daily at 09:00 UTC	Follows back anyone who follows you but you don't follow back
Unfollow	Daily at 18:00 UTC	Unfollows anyone you follow who doesn't follow you back

Both jobs run automatically once deployed — no manual intervention needed.

---

🧠 Smart Bot Filter

Before following anyone back, the bot checks their profile and skips them if:

• Their account type is Bot
• Their username ends with [bot]
• Their account is less than 30 days old
• They fail 2 or more of these checks:
  • No public repositories
  • No bio
  • No followers

This keeps your following list clean and human-only.

---

⚙️ Rate Limiting

The bot is designed to stay within GitHub's unofficial limits:

• 5 second delay between each follow/unfollow
• 10 minute cooldown every 50 actions
• Max 100 actions per run
• Follow and unfollow jobs run 9 hours apart — never at the same time

---

🚀 Deploy on Render (Free)

1. Fork this repo

Click Fork at the top right of this page.

2. Create a GitHub Token

1. Go to GitHub Settings → Developer Settings → Personal Access Tokens
2. Click Generate new token (classic)
3. Give it a name like github-orbit
4. Check the user:follow scope
5. Copy the token

3. Deploy to Render

1. Go to render.com and sign up (free)
2. Click New → Web Service
3. Connect your forked repo
4. Set the following:

Field	Value
Environment	Node
Build Command	npm install
Start Command	npm start

5. Add environment variables:

Key	Value
GITHUB_TOKEN	your token from step 2
GITHUB_USERNAME	your GitHub username

6. Click Deploy

That's it. The bot will start and run on schedule forever.

---

📊 Status Page

Once deployed, visit your Render URL to see the bot status:

{
  "bot": "github-orbit",
  "user": "yourusername",
  "status": "idle",
  "lastFollow": "2024-01-15T09:00:00.000Z",
  "lastUnfollow": "2024-01-15T18:00:00.000Z",
  "schedule": {
    "follow": "daily at 09:00 UTC",
    "unfollow": "daily at 18:00 UTC"
  }
}

---

🗂️ Project Structure

github-orbit/
├── src/
│   ├── server.js       # Express server + cron scheduler
│   ├── github.js       # GitHub API helpers + bot filter
│   ├── followJob.js    # Follow-back logic
│   └── unfollowJob.js  # Unfollow logic
├── .env                # Local env vars (never commit this)
├── .gitignore
├── package.json
└── README.md

---

🔒 Safety Notes

• Never commit your .env file — it's in .gitignore
• The token only needs user:follow scope — nothing else
• The bot will never follow/unfollow more than 100 users per run
• Render's free tier keeps the service alive 24/7

---

📄 License

MIT