euchre_camp/.gitea/WORKFLOW_ARCHITECTURE.md

Gitea Actions Workflow Architecture

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

Overview

The workflow architecture uses a two-step process:

1. PR Workflow: Analyzes commits and suggests bump type
2. Release Workflow: Bumps version, creates tags, and builds Docker images on merge

Workflow Files

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

Trigger: Pull requests to main branch

Purpose:

• Run unit tests on every PR
• Analyze commits to determine bump type (major/minor/patch)
• Comment the suggested bump type on the PR

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/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
• 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

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

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

Future Enhancements

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