claude-home/server-configs/gitea/workflow-templates/README.md

# 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:**
   ```bash
   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:**
   ```bash
   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:**
```bash
# 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:**
```bash
# Modify parsing to handle versions like "1.2.3-beta"
IFS='-' read -r VERSION_NUMBER PRERELEASE <<< "$PR_VERSION"
```

### Add More Notifications

**Slack webhook:**
```yaml
- 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:**
```yaml
- 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:

```yaml
- 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:

```yaml
- 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:

```yaml
- 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