claude-home/server-configs/gitea/INDEX.md

Gitea Configuration & Templates Index

Quick reference for all Gitea-related documentation and templates.

📁 Directory Structure

/server-configs/gitea/
├── README.md                        # Gitea LXC setup and configuration
├── INDEX.md                         # This file - quick reference
├── deployment-strategies.md         # When/how to deploy (manual vs auto)
├── harbor-registry-setup.md         # Self-hosted Docker registry guide
├── apply_branch_protection.py       # Script for branch protection rules
└── workflow-templates/              # Reusable CI/CD templates
    ├── README.md                    # Template usage guide
    ├── docker-build-template.yml    # Complete Docker CI/CD workflow
    ├── deploy-script-template.sh    # Safe manual deployment script
    └── snippets/                    # Workflow code snippets
        └── auto-deploy-with-rollback.yml

🚀 Quick Links

Getting Started

• New to Gitea Actions? → Start with workflow-templates/README.md
• Need a workflow? → Copy docker-build-template.yml
• Want to deploy? → Read deployment-strategies.md

Templates

Docker Build Workflow

File: workflow-templates/docker-build-template.yml

Features:

• ✅ Semantic version validation
• ✅ Docker build + push to Docker Hub
• ✅ Discord notifications
• ✅ Build caching
• ✅ Multi-tag strategy

Use for:

• Discord bots
• Web applications
• API services
• Any Dockerized project

Manual Deploy Script

File: workflow-templates/deploy-script-template.sh

Features:

• ✅ Pre-deployment checks
• ✅ Confirmation prompts
• ✅ Status verification
• ✅ Log viewing
• ✅ Rollback instructions

Use when:

• You want manual control
• Deploying to production
• Testing new deployments

Auto-Deploy with Rollback

File: workflow-templates/snippets/auto-deploy-with-rollback.yml

Features:

• ✅ SSH deployment
• ✅ Health checks
• ✅ Automatic rollback
• ✅ Deployment notifications

Use when:

• You have good test coverage
• Health checks are implemented
• Downtime is acceptable

Guides

Deployment Strategies

File: deployment-strategies.md

Covers:

• Decision framework (when to auto-deploy)
• 5 levels of deployment automation
• Recommendations by project type
• Safety best practices
• Rollback procedures

Read this before: Adding auto-deploy to any project

Harbor Registry Setup

File: harbor-registry-setup.md

Covers:

• Self-hosted Docker registry
• Complete Harbor installation
• Integration with Gitea Actions
• Vulnerability scanning
• Backup strategies

Use when:

• You want private registries
• You hit Docker Hub rate limits
• You want full control
• Learning opportunity

📝 Reference Implementations

Paper Dynasty Discord Bot

Status: ✅ Production Date: 2026-02-04

Setup:

• Gitea Actions on LXC 225
• Docker build + push to Docker Hub
• Discord notifications working
• Manual deployment to sba-bots (10.10.0.88)

Workflow: Based on docker-build-template.yml

What worked:

• Semantic version validation
• Multi-tag strategy (latest, version, version+commit)
• Discord webhooks with ISO 8601 timestamps
• GitHub Actions cache for faster builds

Lessons learned:

• Timestamp format critical for Discord (ISO 8601)
• Health checks needed before auto-deploy
• Manual deploy preferred for production Discord bots

🔧 Common Tasks

Create New Project Workflow

cd /path/to/your/repo
mkdir -p .gitea/workflows
cp /path/to/docker-build-template.yml .gitea/workflows/docker-build.yml

# Customize:
# - Replace "yourusername/yourrepo" with your Docker Hub repo
# - Replace "Your Project" in notifications
# - Replace Discord webhook URLs
# - Add secrets: DOCKERHUB_USERNAME, DOCKERHUB_TOKEN
# - Create VERSION file: echo "1.0.0" > VERSION

Add Auto-Deploy (When Ready)

# Copy auto-deploy snippet
cat workflow-templates/snippets/auto-deploy-with-rollback.yml

# Add to your workflow after build step
# Configure secrets: DEPLOY_SSH_KEY, PRODUCTION_HOST, DEPLOY_USER

Manual Deploy

# Copy deploy script to your repo
cp workflow-templates/deploy-script-template.sh /path/to/repo/deploy.sh
chmod +x /path/to/repo/deploy.sh

# Customize server details in script
# Then use: ./deploy.sh v1.2.3

🎓 Learning Path

1. Start: Read workflow-templates/README.md
2. Setup: Deploy Gitea Actions runner (see README.md)
3. First workflow: Copy docker-build-template.yml
4. Deploy: Use deploy-script-template.sh
5. Advanced: Read deployment-strategies.md
6. Optional: Set up Harbor with harbor-registry-setup.md

🆘 Troubleshooting

Version validation failing

• Check VERSION file format: just 1.2.3
• Ensure semver rules followed
• See template comments for valid bumps

Docker Hub push failing

• Verify secrets set in Gitea
• Check Docker Hub token permissions
• Ensure repo name matches exactly

Discord notifications not appearing

• Verify webhook URL still valid
• Check timestamp format (ISO 8601)
• Test webhook manually with curl

More help

• Check specific template comments
• Read troubleshooting sections in guides
• Review Paper Dynasty as reference implementation

📚 External Resources

• Gitea Actions Docs
• Docker Build Push Action
• Semantic Versioning
• Discord Webhooks
• Harbor Docs

🔄 Maintenance

Update this index when:

• Adding new templates
• Creating new guides
• Changing directory structure
• Adding reference implementations

Last updated: 2026-02-04

---

Quick search tips:

• Need deployment guide? → deployment-strategies.md
• Need workflow template? → workflow-templates/
• Need self-hosted registry? → harbor-registry-setup.md
• Need deploy script? → deploy-script-template.sh