Petbot/GITHUB_AUTH_SETUP.md

GitHub Authentication Setup Guide

GitHub requires secure authentication for pushing code. Choose one of these methods:

🔑 Option 1: SSH Keys (Recommended)

SSH keys are more secure and convenient - no password prompts after setup.

Setup Steps:

1. Generate SSH key (if you don't have one):

   ssh-keygen -t ed25519 -C "your_email@example.com"
   # Press Enter to accept default file location
   # Enter a secure passphrase (optional but recommended)
   

2. Add SSH key to ssh-agent:

   eval "$(ssh-agent -s)"
   ssh-add ~/.ssh/id_ed25519
   

3. Copy public key to clipboard:

   cat ~/.ssh/id_ed25519.pub
   # Copy the entire output
   

4. Add key to GitHub:

   • Go to: https://github.com/settings/keys
   • Click "New SSH key"
   • Paste your public key
   • Give it a descriptive title
   • Click "Add SSH key"

5. Test connection:

   ssh -T git@github.com
   # Should say: "Hi username! You've successfully authenticated"
   

6. Use SSH repository URL:

   • Format: git@github.com:username/repository.git
   • Example: git@github.com:megaproxy/petbot-irc-game.git

---

🎫 Option 2: Personal Access Token

Use HTTPS with a token instead of your password.

Setup Steps:

1. Create Personal Access Token:

   • Go to: https://github.com/settings/tokens
   • Click "Generate new token" → "Generate new token (classic)"
   • Give it a descriptive name: "PetBot Development"
   • Select scopes:
     • ✅ repo (for private repositories)
     • ✅ public_repo (for public repositories)
   • Click "Generate token"
   • Copy the token immediately (you won't see it again!)

2. Use HTTPS repository URL:

   • Format: https://github.com/username/repository.git
   • Example: https://github.com/megaproxy/petbot-irc-game.git

3. When prompted for password:

   • Username: Your GitHub username
   • Password: Use your Personal Access Token (NOT your account password)

4. Optional: Store credentials (so you don't have to enter token every time):

   git config --global credential.helper store
   # After first successful push, credentials will be saved
   

---

🚀 After Authentication Setup

Once you've set up authentication, you can proceed with the GitHub setup:

1. Create GitHub repository at https://github.com/new
2. Run our setup script:

   ./setup-github.sh
   

3. Choose your authentication method (SSH or Token)
4. Enter your repository URL
5. Done! Future pushes will be automatic

---

🔧 Troubleshooting

SSH Issues:

• "Permission denied": Check if SSH key is added to GitHub
• "Could not open a connection": Check SSH agent with ssh-add -l
• "Bad owner or permissions": Fix with chmod 600 ~/.ssh/id_ed25519

Token Issues:

• "Authentication failed": Make sure you're using the token, not your password
• "Remote access denied": Check token has correct scopes (repo/public_repo)
• "Token expired": Create a new token at https://github.com/settings/tokens

General Issues:

• "Repository not found": Check repository URL and access permissions
• "Updates were rejected": Repository might not be empty - contact support

---

📚 Official Documentation

• SSH Keys: https://docs.github.com/en/authentication/connecting-to-github-with-ssh
• Personal Access Tokens: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token
• Git Authentication: https://docs.github.com/get-started/getting-started-with-git/about-remote-repositories