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:

• ✅ CalVer versioning (YYYY.MM.BUILD) via shared cal/gitea-actions/calver action
• ✅ Docker build + push to Docker Hub
• ✅ Discord notifications via shared cal/gitea-actions/discord-notify action
• ✅ Git tagging via shared cal/gitea-actions/gitea-tag action
• ✅ Build caching (registry-based)
• ✅ Multi-tag strategy (latest, version, version+sha, dev)

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

Projects Using Shared Actions

All use cal/gitea-actions composite actions (CalVer, git tagging, Discord notify):

Project	Workflow	Type
major-domo-database	docker-build.yml	Docker build + push
paper-dynasty-discord	docker-build.yml	Docker build + push
paper-dynasty-database	build.yml	Docker build + push
major-domo-v2	docker-build.yml	Docker build + push
vagabond-rpg-foundryvtt	deploy.yml	Build + rsync deploy

Lessons Learned

• Runner GITEA_INSTANCE_URL must use internal IP, not public domain (host mismatch breaks auth)
• DEFAULT_ACTIONS_URL=self + short-form refs for local actions, full URLs for GitHub actions
• REQUIRE_SIGNIN_VIEW=false is safe — only public repos are exposed, private repos stay locked
• Registry-based Docker build cache (type=registry) requires Docker Hub login on every build
• Manual deploy preferred for production Discord bots (health checks needed before auto-deploy)

🔧 Common Tasks

Create New Project Workflow

cd /path/to/your/repo
mkdir -p .gitea/workflows

# Copy from an existing project (e.g., major-domo-database)
cp /mnt/NV2/Development/major-domo/database/.gitea/workflows/docker-build.yml \
   .gitea/workflows/docker-build.yml

# Customize:
# - Replace Docker Hub image name (manticorum67/your-project)
# - Replace project title in Discord notifications
# - Add repo secrets: DOCKERHUB_USERNAME, DOCKERHUB_TOKEN, DISCORD_WEBHOOK
#
# Action reference rules (DEFAULT_ACTIONS_URL=self):
# - Local actions: short form (cal/gitea-actions/calver@main)
# - GitHub actions: full URL (https://github.com/actions/checkout@v4)

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

CalVer version looks wrong

• CalVer is auto-generated from git tags (YYYY.MM.BUILD)
• BUILD number counts tags in the current month
• Ensure fetch-depth: 0 in checkout step (needs full tag history)

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-18

---

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