# 🔑 GitHub Token Setup Guide

## 🎯 **Why You Need This**

The Gitea Actions workflows use Trivy for security scanning, which needs to download vulnerability databases from GitHub. Without a GitHub token, you'll hit rate limits and the security scans will fail.

## 🚀 **Quick Setup (5 minutes)**

### **Step 1: Create GitHub Personal Access Token**

1. **Go to GitHub**: https://github.com/settings/tokens
2. **Click "Generate new token"** → "Generate new token (classic)"
3. **Configure the token**:
   - **Note**: `B4L Ping River Monitor - Gitea Actions`
   - **Expiration**: `90 days` (or longer)
   - **Scopes**: Select `public_repo` (for public repositories)
4. **Click "Generate token"**
5. **Copy the token** (you won't see it again!)

### **Step 2: Add Token to Gitea Repository**

1. **Go to your repository**: https://git.b4l.co.th/B4L/Northern-Thailand-Ping-River-Monitor
2. **Click "Settings"** (in the repository)
3. **Click "Secrets"** in the left sidebar
4. **Click "Add Secret"**
5. **Configure the secret**:
   - **Name**: `GITHUB_TOKEN`
   - **Value**: Paste the token you copied from GitHub
6. **Click "Add Secret"**

### **Step 3: Verify It's Working**

1. **Trigger a workflow** by pushing a commit or manually running the security workflow
2. **Check the Actions tab** in your repository
3. **Look for the message**: `✅ GITHUB_TOKEN is configured`

## 🔒 **Security Best Practices**

### **Token Permissions**
- **Minimum required**: `public_repo` scope
- **Never use**: `repo` scope unless you need private repo access
- **Avoid**: Admin or write permissions

### **Token Management**
- **Set expiration**: Don't create tokens that never expire
- **Regular rotation**: Update tokens every 90 days
- **Monitor usage**: Check GitHub token usage in settings

### **Repository Security**
- **Only trusted contributors**: Should have access to repository secrets
- **Audit regularly**: Review who has access to secrets
- **Use organization secrets**: For multiple repositories

## 🧪 **Testing the Setup**

### **Manual Test**
```bash
# Trigger the security workflow manually
# Go to: Repository → Actions → Security & Dependency Updates → Run workflow
```

### **Automatic Test**
```bash
# Push any change to trigger workflows
git commit --allow-empty -m "Test GitHub token setup"
git push
```

### **Check Workflow Logs**
1. Go to Actions tab in your repository
2. Click on the latest "Security & Dependency Updates" run
3. Click on "Docker Security Scan" job
4. Look for: `✅ GITHUB_TOKEN is configured`

## ❌ **Troubleshooting**

### **"GITHUB_TOKEN not configured" message**
- **Problem**: Token not added to repository secrets
- **Solution**: Follow Step 2 above, ensure exact name `GITHUB_TOKEN`

### **"Bad credentials" error**
- **Problem**: Token is invalid or expired
- **Solution**: Generate a new token and update the secret

### **Rate limit errors**
- **Problem**: Token doesn't have correct permissions
- **Solution**: Ensure token has `public_repo` scope

### **Trivy still failing**
- **Problem**: Network issues or GitHub API problems
- **Solution**: Wait and retry, or check GitHub status page

## 🎉 **Success Indicators**

When everything is working correctly, you'll see:

✅ **In workflow logs**: `✅ GITHUB_TOKEN is configured`  
✅ **Security scans**: Complete without authentication errors  
✅ **Trivy reports**: Generated and uploaded as artifacts  
✅ **No rate limit errors**: In the workflow execution  

## 📚 **Additional Resources**

- [GitHub Personal Access Tokens Documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)
- [Gitea Secrets Documentation](https://docs.gitea.io/en-us/usage/actions/#secrets)
- [Trivy Action Documentation](https://github.com/aquasecurity/trivy-action)

---

**Setup Time**: ~5 minutes  
**Token Validity**: 90 days (recommended)  
**Security Level**: High (read-only public repo access)  

Your workflows will now run smoothly with proper GitHub API authentication! 🚀