grabowski
557b29b74d
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
114 lines
4.0 KiB
Markdown
114 lines
4.0 KiB
Markdown
# 🔑 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! 🚀 |