euchre_camp/.gitea/WORKFLOW_ARCHITECTURE.md

Gitea Actions Workflow Architecture

This document describes the workflow architecture for version bumping, testing, and releases.

Overview

The workflow architecture uses a three-step process:

1. PR Workflow: Runs tests on PRs and analyzes commits for bump type
2. Test Workflow: Runs unit tests on all branch pushes (except version bumps)
3. Release Workflow: Bumps version, creates tags, builds Docker images, and deploys on main branch pushes

Workflow Files

1. .gitea/workflows/pr.yml (Pull Request Workflow)

Trigger: Pull requests to main branch

Purpose:

• Run unit tests on every PR (fast feedback)
• Run acceptance tests with SQLite database
• Analyze commits to determine bump type (major/minor/patch)
• Comment the suggested bump type on the PR

Test Execution:

• Unit Tests: Run first, fast execution
• Acceptance Tests: Run after unit tests pass, uses SQLite database
• Database: SQLite with DATABASE_URL=file:./prisma/ci.db
• Secrets: Uses BETTER_AUTH_SECRET for authentication

Bump Type Detection:

• Major: Breaking changes detected (BREAKING CHANGE or !: in commit messages)
• Minor: Feature commits detected (feat: prefix)
• Patch: Default for fixes and other changes

2. .gitea/workflows/test.yml (Test Workflow)

Trigger: Pushes to any branch (including main)

Purpose:

• Run unit tests on all branch pushes
• Skip auto-generated version bump commits (handled by release workflow)

Key Features:

• Runs on all branches including main
• Skips commits with "chore: bump version" message
• Fast execution for quick feedback

3. .gitea/workflows/release.yml (Release Workflow)

Trigger: Pushes to main branch (after PR merge)

Purpose:

• Determine bump type from merge commit or PR commits
• Bump version in package.json and CHANGELOG.md
• Commit the version bump
• Create git tag for the release
• Run tests inside Docker container (with PostgreSQL)
• Build production Docker image
• Push images to registry
• Deploy to dev environment

Key Features:

• Skips commits that are auto-generated version bumps
• Uses DOCKER_LOGIN and DOCKER_PASSWORD secrets for registry auth
• Handles existing git tags gracefully
• Runs comprehensive tests in production-like environment

Version Bump Logic

Step 1: PR Analysis (pr.yml)

When a PR is opened or updated:

1. Fetch the merge base with main
2. Analyze all commits in the PR
3. Determine bump type based on commit messages:
   • Breaking changes → major
   • Features → minor
   • Fixes → patch
4. Comment the suggested bump type on the PR

Step 2: Release (release.yml)

When a PR is merged to main:

1. Check if the commit is an auto-bump (skip if so)
2. Analyze the merge commit message or PR commits
3. Run node scripts/bump-version.js <type> --yes
4. Commit the version bump changes
5. Create and push git tag
6. Build and push Docker images

Environment Variables & Secrets

Required Secrets

• DOCKER_LOGIN: Username for Docker registry authentication
• DOCKER_PASSWORD: Password for Docker registry authentication
• GITEA_TOKEN (optional): For pushing back to repo (if needed)

Environment Variables

• REGISTRY: Docker registry URL (default: docker.notsosm.art)
• IMAGE_NAME: Docker image name (default: euchre-camp)

Example Workflow

Scenario: Feature PR

1. Developer opens PR with commits:
   • "feat: add new feature"
   • "fix: resolve edge case"
2. PR workflow runs:
   • Unit tests pass
   • Bump type analysis suggests "minor"
   • Comment posted on PR: "Suggested bump: MINOR"
3. Developer merges PR
4. Release workflow runs:
   • Detects minor bump from commits
   • Bumps version from 0.1.1 → 0.2.0
   • Commits version bump
   • Creates tag v0.2.0
   • Builds and pushes Docker image
   • Deploys to dev

Scenario: Breaking Change PR

1. Developer opens PR with commit:
   • "feat!: breaking API change"
2. PR workflow runs:
   • Detects breaking change marker
   • Suggests "major" bump
   • Comments on PR
3. Developer merges PR
4. Release workflow runs:
   • Detects major bump
   • Bumps version from 0.1.1 → 1.0.0
   • Creates tag v1.0.0
   • Proceeds with build and deploy

Database Configuration for CI

SQLite for CI Acceptance Tests

• Why SQLite: No database server required, perfect for CI environments
• Usage: PR workflow runs acceptance tests with SQLite database
• Configuration: DATABASE_PROVIDER=sqlite, DATABASE_URL=file:./prisma/ci.db
• Benefits: Fast, isolated, no external dependencies

PostgreSQL for Production

• Usage: Release workflow runs tests in Docker with PostgreSQL
• Configuration: Uses dummy PostgreSQL URL for Docker builds
• Benefits: Production-like environment, catches PostgreSQL-specific issues

Database Provider Detection

The application automatically detects the database provider:

• DATABASE_PROVIDER environment variable (defaults to sqlite)
• prisma.ts conditionally uses PrismaPg adapter for PostgreSQL
• Better Auth configured with appropriate provider

Benefits

1. No CI Loops: Version bump commits are detected and skipped
2. Clear Communication: PR comments inform developers of impact
3. Semantic Versioning: Automated adherence to semver rules
4. Traceability: Git tags and changelog reflect all changes
5. Safe Releases: Tests run before version bump and deployment
6. Fast CI: SQLite tests run quickly without database server setup
7. Comprehensive Testing: Both unit and acceptance tests in PR workflow

Future Enhancements

• Add GitHub/Gitea Release creation
• Slack/Discord notifications on release
• Automatic rollback on test failure
• Multi-environment deployment (dev/staging/prod)