claude-home/server-configs/gitea/workflow-templates

Gitea Actions Workflow Templates

Reusable CI/CD workflow templates for Gitea Actions (GitHub Actions compatible).

Templates

docker-build-template.yml

Complete Docker build pipeline with semantic versioning validation, Docker Hub push, and Discord notifications.

Features:

• ✅ Semantic version validation on PRs
• ✅ Docker build on every push/PR
• ✅ Push to Docker Hub on main branch
• ✅ Discord notifications (success/failure)
• ✅ Build caching for faster builds
• ✅ Multi-tag strategy (latest, version, version+commit)

Reference Implementation: Paper Dynasty Discord bot - First production use (2026-02-04)

Quick Start

1. Copy template to your repo:

   mkdir -p .gitea/workflows
   cp docker-build-template.yml .gitea/workflows/docker-build.yml
   

2. Customize placeholders:

   • Replace yourusername/yourrepo with your Docker Hub repository
   • Replace Your Project in notification titles
   • Replace YOUR_DISCORD_WEBHOOK_URL_HERE with your webhook URLs

3. Add Gitea secrets:

   • Go to your repo → Settings → Secrets → Actions
   • Add DOCKERHUB_USERNAME (your Docker Hub username)
   • Add DOCKERHUB_TOKEN (access token from hub.docker.com)

4. Create VERSION file:

   echo "1.0.0" > VERSION
   git add VERSION
   git commit -m "Add initial VERSION file"
   

5. Push and test:

   • Create a PR to test version validation
   • Merge to main to test Docker push and notifications

Customization Guide

Disable Features

Don't want version validation?

• Delete the "Check VERSION was bumped" step

Don't want Discord notifications?

• Delete both "Discord Notification" steps

Don't want Docker Hub push?

• Remove "Login to Docker Hub" step
• Change push: ${{ github.ref == 'refs/heads/main' }} to push: false

Customize Version Validation

The template enforces strict semantic versioning. To modify:

Allow any version bump:

# Remove the validation logic, just check if changed:
if [ "$PR_VERSION" = "$MAIN_VERSION" ]; then
  echo "❌ VERSION unchanged"
  exit 1
fi
echo "✅ VERSION changed: $MAIN_VERSION → $PR_VERSION"

Allow pre-release versions:

# Modify parsing to handle versions like "1.2.3-beta"
IFS='-' read -r VERSION_NUMBER PRERELEASE <<< "$PR_VERSION"

Add More Notifications

Slack webhook:

- name: Slack Notification
  if: success() && github.ref == 'refs/heads/main'
  run: |
    curl -X POST YOUR_SLACK_WEBHOOK_URL \
      -H 'Content-Type: application/json' \
      -d '{"text": "Build succeeded: v${{ steps.meta.outputs.version }}"}'    

Email notification:

- name: Email Notification
  if: failure()
  uses: dawidd6/action-send-mail@v3
  with:
    server_address: smtp.gmail.com
    server_port: 465
    username: ${{ secrets.EMAIL_USERNAME }}
    password: ${{ secrets.EMAIL_PASSWORD }}
    subject: Build Failed - ${{ github.repository }}
    body: Build failed on commit ${{ github.sha }}
    to: you@example.com

Troubleshooting

Version Validation Issues

Problem: PR fails validation but VERSION was bumped Solution: Check VERSION file format - should be just 1.2.3 with no prefix, suffix, or extra text

Problem: Validation allows invalid bumps Solution: Version parsing may be failing - check for special characters in VERSION file

Docker Hub Push Issues

Problem: Login fails with "unauthorized" Solution: Regenerate Docker Hub access token at hub.docker.com → Settings → Security

Problem: Push fails with "denied" Solution: Check repository name matches exactly (case-sensitive)

Problem: Tags not appearing on Docker Hub Solution: Wait a few seconds and refresh - tags may take a moment to appear

Discord Notification Issues

Problem: Webhook succeeds but no message appears Solution:

1. Check timestamp format is ISO 8601: YYYY-MM-DDTHH:MM:SSZ
2. Test webhook manually with curl
3. Verify webhook hasn't been deleted in Discord

Problem: Message appears malformed Solution: Check for unescaped quotes or special characters in message content

Problem: Rate limited Solution: Discord limits webhooks to ~5 messages per second - add delays if sending multiple

Advanced Usage

Multi-Stage Builds

Add test/lint steps before build:

- name: Run tests
  run: |
    npm install
    npm test    

- name: Lint code
  run: npm run lint

- name: Build Docker image
  # ... existing build step

Deploy After Build

Add deployment to production:

- name: Deploy to production
  if: success() && github.ref == 'refs/heads/main'
  run: |
    ssh production "docker pull yourusername/yourrepo:latest && docker-compose up -d"    

Multiple Docker Registries

Push to multiple registries:

- name: Login to GitHub Container Registry
  uses: docker/login-action@v3
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}

- name: Build Docker image
  uses: docker/build-push-action@v5
  with:
    push: ${{ github.ref == 'refs/heads/main' }}
    tags: |
      yourusername/yourrepo:latest
      ghcr.io/yourusername/yourrepo:latest      

Template Updates

This template was created based on the Paper Dynasty Discord bot workflow and represents battle-tested CI/CD practices. Future improvements might include:

• Automatic changelog generation from commits
• Security scanning (Trivy, Snyk)
• Multi-architecture builds (ARM, AMD64)
• Deployment strategies (blue-green, canary)
• Integration testing with docker-compose
• Performance benchmarking

Contributing

Found a bug or improvement? Update this template and document the change in this README.

License

Free to use and modify for any project.

---

Template Version: 1.0.0 Last Updated: 2026-02-04 Maintained By: Manticorum Home Lab