major-domo-database/GITEA_ACTIONS_SETUP.md

# Gitea Actions Setup for Major Domo Database

Complete CI/CD pipeline for automated Docker builds, semantic versioning, and Discord notifications.

## Overview

The Gitea Actions workflow in `.gitea/workflows/docker-build.yml` provides:

- ✅ Semantic version validation on pull requests
- ✅ Automated Docker image builds
- ✅ Push to Docker Hub on main branch merges
- ✅ Discord notifications for build success/failure
- ✅ Multi-tag strategy (latest, version, version+commit)
- ✅ Build caching for faster builds

## Initial Setup

### 1. Create Docker Hub Access Token

1. Go to https://hub.docker.com
2. Login → Account Settings → Security
3. Click "New Access Token"
4. Name: `gitea-major-domo-database`
5. Permissions: Read & Write
6. Copy the token (you won't see it again!)

### 2. Add Gitea Secrets

1. Go to https://git.manticorum.com/cal/major-domo-database
2. Navigate to: Settings → Secrets → Actions
3. Add three secrets:

| Secret Name | Value |
|-------------|-------|
| `DOCKERHUB_USERNAME` | `manticorum67` |
| `DOCKERHUB_TOKEN` | [Docker Hub access token from step 1] |
| `DISCORD_WEBHOOK_URL` | [Discord webhook URL for build notifications] |

### 3. Create Discord Webhook (Optional)

If you want build notifications in Discord:

1. Open Discord channel for CI/CD notifications
2. Right-click channel → Edit Channel → Integrations
3. Click "Create Webhook"
4. Name: `Major Domo Database CI`
5. Copy webhook URL
6. Add as `DISCORD_WEBHOOK_URL` secret in Gitea (step 2 above)

### 4. Enable Actions in Repository

1. Go to repository settings in Gitea
2. Navigate to "Workflow" or "Actions" section
3. Enable Actions for this repository

## Usage

### Creating a Pull Request

1. Create a feature branch:
   ```bash
   git checkout -b feature/my-feature
   ```

2. Make your changes

3. **Bump the VERSION file** (required for PR approval):
   ```bash
   # Current version: 2.4.1
   # For bug fix:
   echo "2.4.2" > VERSION

   # For new feature:
   echo "2.5.0" > VERSION

   # For breaking change:
   echo "3.0.0" > VERSION
   ```

4. Commit and push:
   ```bash
   git add .
   git commit -m "Add new feature"
   git push origin feature/my-feature
   ```

5. Create PR in Gitea

**The workflow will:**
- ✅ Validate the VERSION bump follows semantic versioning
- ✅ Build the Docker image (but not push it)
- ❌ Block the PR if VERSION wasn't bumped or is invalid

### Merging to Main

When you merge the PR to main:

**The workflow will:**
1. Build the Docker image
2. Push to Docker Hub with three tags:
   - `manticorum67/major-domo-database:latest`
   - `manticorum67/major-domo-database:v2.4.2`
   - `manticorum67/major-domo-database:v2.4.2-a1b2c3d`
3. Send Discord notification (if configured)
4. Create build summary in Actions UI

## Semantic Versioning Rules

The workflow enforces strict semantic versioning:

### Valid Version Bumps

| Type | Example | When to Use |
|------|---------|-------------|
| **Patch** | 2.4.1 → 2.4.2 | Bug fixes, minor tweaks |
| **Minor** | 2.4.1 → 2.5.0 | New features, backward compatible |
| **Major** | 2.4.1 → 3.0.0 | Breaking changes |

### Invalid Version Bumps

❌ Skipping versions: `2.4.1 → 2.6.0` (skipped 2.5.0)
❌ Going backwards: `2.4.1 → 2.3.0`
❌ Not resetting: `2.4.1 → 2.5.1` (should be 2.5.0)
❌ No change: `2.4.1 → 2.4.1`

## Manual Deployment

Use the included `deploy.sh` script for manual deployments:

```bash
# Deploy latest version
./deploy.sh

# Deploy specific version
./deploy.sh v2.4.2
```

The script will:
1. Check SSH connection to production server
2. Verify container exists
3. Ask for confirmation
4. Pull new image
5. Restart container
6. Show status and recent logs

## Deployment Server Details

- **Server**: strat-database (10.10.0.42)
- **User**: cal
- **Path**: /home/cal/container-data/sba-database
- **Container**: sba_database
- **Image**: manticorum67/major-domo-database

## Troubleshooting

### PR Blocked - VERSION Not Updated

**Error:** "VERSION file has not been updated!"

**Solution:** Update the VERSION file in your branch:
```bash
echo "2.4.2" > VERSION
git add VERSION
git commit -m "Bump version to 2.4.2"
git push
```

### PR Blocked - Invalid Semantic Version

**Error:** "Invalid semantic version change!"

**Solution:** Follow semantic versioning rules. From 2.4.1:
- Bug fix → `2.4.2` (not 2.4.3, 2.5.0, etc.)
- New feature → `2.5.0` (not 2.6.0, 2.5.1, etc.)
- Breaking change → `3.0.0` (not 4.0.0, 3.1.0, etc.)

### Docker Hub Push Failed

**Error:** "unauthorized: authentication required"

**Solution:**
1. Verify `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN` secrets are set
2. Check Docker Hub token hasn't expired
3. Regenerate token if needed and update secret

### Discord Notifications Not Appearing

**Problem:** Build succeeds but no Discord message

**Solutions:**
1. Verify `DISCORD_WEBHOOK_URL` secret is set correctly
2. Test webhook manually:
   ```bash
   curl -H "Content-Type: application/json" \
     -d '{"content": "Test message"}' \
     YOUR_WEBHOOK_URL
   ```
3. Check webhook still exists in Discord channel settings

### Build Failing on Main but PR Passed

**Possible causes:**
1. Merge conflict not resolved properly
2. Dependencies changed between PR and merge
3. Docker Hub credentials invalid

**Solution:**
1. Check Actions logs in Gitea
2. Look for specific error messages
3. Test build locally:
   ```bash
   docker build -t test-build .
   ```

## Viewing Build Status

### In Gitea

1. Go to repository → Actions
2. Click on workflow run to see details
3. View step-by-step logs
4. Check build summary

### In Discord

If webhook is configured, you'll get:
- ✅ Green embed on successful builds
- ❌ Red embed on failed builds
- Version, commit, and Docker Hub link

### On Docker Hub

1. Go to https://hub.docker.com/r/manticorum67/major-domo-database
2. Check "Tags" tab for new versions
3. Verify timestamp matches your push

## Advanced Usage

### Disable Version Validation

If you need to merge without version bump (not recommended):

1. Edit `.gitea/workflows/docker-build.yml`
2. Delete or comment out the "Check VERSION was bumped" step
3. Commit and push

### Disable Discord Notifications

1. Edit `.gitea/workflows/docker-build.yml`
2. Delete both "Discord Notification" steps
3. Commit and push

### Add Additional Tags

Edit the "Build Docker image" step in the workflow:

```yaml
tags: |
  manticorum67/major-domo-database:latest
  manticorum67/major-domo-database:v${{ steps.meta.outputs.version }}
  manticorum67/major-domo-database:${{ steps.meta.outputs.version_sha }}
  manticorum67/major-domo-database:stable  # Add custom tag  
```

## Workflow File Location

The workflow is located at:
```
.gitea/workflows/docker-build.yml
```

This file is tracked in git and will be used automatically by Gitea Actions when:
- You push to main branch
- You create a pull request to main branch

## Related Documentation

- [Docker Build Template](/mnt/NV2/Development/claude-home/server-configs/gitea/workflow-templates/docker-build-template.yml)
- [Gitea Actions Documentation](https://git.manticorum.com/gitea/docs)
- [Semantic Versioning Specification](https://semver.org/)

## Questions or Issues?

If you encounter problems:
1. Check Actions logs in Gitea
2. Review this troubleshooting section
3. Test components manually (Docker build, webhook, etc.)
4. Check Gitea Actions runner status

---

**Last Updated:** 2026-02-04
**Current Version:** 2.4.1
**Template Version:** 1.0.0 (based on paper-dynasty-database)