# 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):
   ```bash
   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**:
   ```bash
   eval "$(ssh-agent -s)"
   ssh-add ~/.ssh/id_ed25519
   ```

3. **Copy public key to clipboard**:
   ```bash
   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**:
   ```bash
   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):
   ```bash
   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**:
   ```bash
   ./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