Critical: Implement automated release process

[tbrandenburg]

Problem

The repository has no formal release process, automated workflows, or release artifacts. This creates critical deployment and user confidence issues:

• Users cannot access stable, tested versions
• No clear communication of changes between versions
• Manual deployment processes are error-prone and non-reproducible
• Lack of release artifacts reduces deployment confidence

Evidence

• No release-related GitHub Actions workflows
• No GitHub Releases published
• Makefile contains only development tasks (no release commands)
• No changelog generation or release notes

Impact

Critical - Users cannot reliably deploy or upgrade the application.

Recommended Solution

1. Create automated release workflow triggered by version tags
2. Generate GitHub Releases with automatic changelog
3. Build and publish artifacts:
   • Container images with version tags
   • Release binaries/packages
4. Implement release notes generation

Acceptance Criteria

• Create .github/workflows/release.yml workflow
• Workflow triggers on version tag push (v*..)
• Automatically generate and publish GitHub Release
• Build and tag container images with versions
• Generate changelog from commit messages
• Include release artifacts (containers, packages)
• Add release documentation to README

Priority

Critical - Enables reliable production deployments

[github-actions]

Investigation: Critical: Implement automated release process

Issue: #301 (#301)
Type: ENHANCEMENT
Investigated: 2026-03-15T18:45:00Z

Assessment

Metric	Value	Reasoning
Priority	HIGH	Issue explicitly states "Critical" and blocks reliable production deployments
Complexity	MEDIUM	Requires new workflow file, Makefile updates, and container tagging - 3 files with moderate integration
Confidence	HIGH	Clear requirements from issue, existing CI/CD workflows to follow as patterns

---

Problem Statement

The repository lacks a formal release process with automated workflows and release artifacts. This prevents users from accessing stable, tested versions and creates deployment and reproducibility issues. The current setup has no way to version releases, generate changelogs, or publish artifacts.

---

Analysis

Change Rationale

The issue explicitly requests implementing an automated release workflow. This is a common CI/CD pattern that:

• Enables semantic versioning through git tags
• Automates release artifact creation
• Generates changelogs from commit history
• Publishes container images with version tags
• Creates GitHub Releases with notes

Evidence

• Current state: No .github/workflows/release.yml exists
• Git tags: None exist (verified with git tag -l)
• pyproject.toml: Version is 0.1.0 at packages/pybackend/pyproject.toml:3
• Existing workflows: Pattern established in .github/workflows/docker.yml
• Makefile: Only development tasks, no release commands (Makefile:1-246)

Affected Files

File	Lines	Action	Description
.github/workflows/release.yml	NEW	CREATE	Automated release workflow
Makefile	246	UPDATE	Add release and bump-version commands
README.md	-	UPDATE	Add release documentation section

Integration Points

• GitHub Actions: Triggers on tag push (v*..)
• Docker: Uses existing docker-compose.yml and Dockerfiles
• Git: Uses annotated tags for versioning
• GitHub API: Creates releases via softprops/action-gh-release

Git History

• No prior release work: This is a new feature implementation
• Implication: No regression risk, greenfield implementation

---

Implementation Plan

Step 1: Create Release Workflow

File: .github/workflows/release.yml
Action: CREATE

Required content:

name: Release

on:
  push:
    tags:
      - 'v*.*.*'

jobs:
  release:
    name: Create Release
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to GitHub Container Registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata
        id: metadata
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/${{ github.repository }}
          tags: |
            type=ref,event=tag
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}
            type=semver,pattern={{major}}

      - name: Get version from tag
        id: version
        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT

      - name: Build and push pybackend image
        uses: docker/build-push-action@v5
        with:
          context: .
          file: docker/pybackend.Dockerfile
          push: true
          tags: ghcr.io/${{ github.repository }}/pybackend:${{ steps.version.outputs.VERSION }}
          labels: ${{ steps.metadata.outputs.labels }}

      - name: Build and push frontend image
        uses: docker/build-push-action@v5
        with:
          context: .
          file: docker/frontend.Dockerfile
          push: true
          tags: ghcr.io/${{ github.repository }}/frontend:${{ steps.version.outputs.VERSION }}
          labels: ${{ steps.metadata.outputs.labels }}

      - name: Generate changelog
        id: changelog
        uses: metcalfc/changelog-generator@v4
        with:
          myToken: ${{ secrets.GITHUB_TOKEN }}

      - name: Create GitHub Release
        uses: softprops/action-gh-release@v1
        with:
          body: ${{ steps.changelog.outputs.changelog }}
          files: |
            dist/*
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Why: This follows the existing workflow pattern from .github/workflows/docker.yml and implements all acceptance criteria from the issue.

---

Step 2: Add Release Commands to Makefile

File: Makefile
Lines: 246
Action: UPDATE

Current code:

.PHONY: help lint format test unit-test system-test qa qa-quick build run stop restart clean install install-node install-pybackend test-coverage security-audit docker-build docker-up docker-down docker-dev docker-clean

Required change:

.PHONY: help lint format test unit-test system-test qa qa-quick build run stop restart clean install install-node install-pybackend test-coverage security-audit docker-build docker-up docker-down docker-dev docker-clean release bump-version

Add after docker-clean (line 246):

# Release Tasks
release:
	@echo "🚀 Creating release..."
	@echo "📋 To create a release:"
	@echo "   1. Run: make bump-version VERSION=x.y.z"
	@echo "   2. Push tag: git push origin vx.y.z"
	@echo "   3. GitHub Actions will automatically build and release"
	@echo ""
	@echo "📦 Release will include:"
	@echo "   - GitHub Release with changelog"
	@echo "   - Container images pushed to GHCR"
	@echo "   - Version tags (v{x.y.z}, v{x.y}, v{x})"

bump-version:
ifndef VERSION
	$(error VERSION is required. Usage: make bump-version VERSION=1.0.0)
endif
	@echo "📝 Bumping version to v$(VERSION)..."
	git tag -a v$(VERSION) -m "Release v$(VERSION)"
	@echo "✅ Created tag v$(VERSION)"
	@echo "🚀 Push with: git push origin v$(VERSION)"

Why: Provides convenient commands for versioning and documents the release process. Follows existing Makefile patterns and conventions.

---

Step 3: Add Release Documentation to README

File: README.md
Action: UPDATE

Add a "Release Process" section:

## Release Process

### Creating a Release

1. **Bump the version**:
   ```bash
   make bump-version VERSION=1.0.0

2. Push the tag:

   git push origin v1.0.0

3. GitHub Actions will automatically:

   • Build and push container images to GHCR
   • Generate a GitHub Release with changelog
   • Create version tags (v1.0.0, v1.0, v1)

Release Artifacts

• Container Images:

  • ghcr.io/<owner>/made/pybackend:<version>
  • ghcr.io/<owner>/made/frontend:<version>

• Version Tags:

  • Full: v1.0.0
  • Minor: v1.0
  • Major: v1
  • Latest: latest

**Why**: Documents the new release process for users. README should be readable to find how releases work.

---

## Patterns to Follow

### From `.github/workflows/docker.yml:1-68`

```yaml
# Pattern for workflow structure
name: Docker Build & Test

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  docker-build:
    name: Docker Build
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
      
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

What this demonstrates: Standard workflow structure with checkout, buildx setup, and build steps to follow.

From Makefile:14

# Pattern for .PHONY declarations
.PHONY: help lint format test unit-test

What this demonstrates: Proper Makefile organization with .PHONY declarations.

---

Edge Cases & Risks

Risk/Edge Case	Mitigation
Tag pushed without changes	Release will be created with existing artifacts; acceptable
Concurrent tag pushes	Sequential releases recommended; workflow runs in parallel
GHCR not enabled on repo	Requires repo admin to enable GHCR; documented in README
Build failure during release	GitHub Actions will fail; release won't be created
Changelog generation fails	Uses fallback empty changelog; release still succeeds

---

Validation

Automated Checks

# Verify workflow syntax
npm run lint:workflows  # If available, or use act to test

# Verify Makefile syntax
make -n release  # Dry-run release target
make -n bump-version VERSION=1.0.0  # Dry-run bump-version target

Manual Verification

1. Create a test release:

   make bump-version VERSION=0.1.1
   git push origin v0.1.1 --dry-run  # Verify first

2. Verify workflow triggers: Check GitHub Actions tab for new workflow run

3. Verify release created: Check GitHub Releases page for new release

4. Verify container images: Check GHCR package registry for pushed images

---

Scope Boundaries

IN SCOPE:

• Creating .github/workflows/release.yml
• Adding release commands to Makefile
• Adding release documentation to README

OUT OF SCOPE (do not touch):

• Changes to existing CI/CD workflows (docker.yml, tests.yml)
• Container registry beyond GHCR (Docker Hub, ECR)
• Python package publishing to PyPI
• NPM package publishing to npmjs
• Release signing with GPG
• Pre-release / beta release workflows

---

Metadata

• Investigated by: GHAR
• Timestamp: 2026-03-15T18:45:00Z
• Artifact: .ghar/issues/issue-301.md

[github-actions]

🕰️ This issue has been inactive for over 3 days.

@tbrandenburg - Could you provide an update on this issue?

If this issue is resolved or no longer relevant, please consider closing it.

[github-actions]

🕰️ This issue has been inactive for over 3 days.

@tbrandenburg - Could you provide an update on this issue?

If this issue is resolved or no longer relevant, please consider closing it.

[github-actions]

🕰️ This issue has been inactive for over 3 days.

@tbrandenburg - Could you provide an update on this issue?

If this issue is resolved or no longer relevant, please consider closing it.

[github-actions]

🕰️ This issue has been inactive for over 3 days.

@tbrandenburg - Could you provide an update on this issue?

If this issue is resolved or no longer relevant, please consider closing it.

[github-actions]

🕰️ This issue has been inactive for over 3 days.

@tbrandenburg - Could you provide an update on this issue?

If this issue is resolved or no longer relevant, please consider closing it.

[github-actions]

🕰️ This issue has been inactive for over 3 days.

@tbrandenburg - Could you provide an update on this issue?

If this issue is resolved or no longer relevant, please consider closing it.