major-domo-database/.claude/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:

   git checkout -b feature/my-feature
   

2. Make your changes

3. Bump the VERSION file (required for PR approval):

   # 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:

   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:

# 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:

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:

   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:

   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:

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
• Gitea Actions Documentation
• Semantic Versioning Specification

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)