Northern-Thailand-Ping-River-Monitor/GITHUB_TOKEN_SETUP.md

🔑 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

# Trigger the security workflow manually
# Go to: Repository → Actions → Security & Dependency Updates → Run workflow

Automatic Test

# 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
• Gitea Secrets Documentation
• Trivy Action Documentation

---

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! 🚀