From 557b29b74ddb160b850916f46478c98becba93a1 Mon Sep 17 00:00:00 2001
From: grabowski <berwn@buildfor.life>
Date: Tue, 12 Aug 2025 16:13:07 +0700
Subject: [PATCH]  Add GitHub token setup guide

 New Documentation:
- Complete step-by-step guide for GitHub token setup
- Security best practices and token management
- Troubleshooting common issues
- Testing and verification instructions

 Benefits:
- Fixes Trivy security scan authentication issues
- Improves workflow reliability and success rates
- Provides clear setup instructions for team members
- Ensures proper security token management
---
 GITHUB_TOKEN_SETUP.md | 114 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 114 insertions(+)
 create mode 100644 GITHUB_TOKEN_SETUP.md

diff --git a/GITHUB_TOKEN_SETUP.md b/GITHUB_TOKEN_SETUP.md
new file mode 100644
index 0000000..132b394
--- /dev/null
+++ b/GITHUB_TOKEN_SETUP.md
@@ -0,0 +1,114 @@
+# 🔑 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! 🚀
\ No newline at end of file