Skip to content

CI_CD_WORKFLOW.md

Latest commit

 

History

History
534 lines (403 loc) · 15.1 KB

CI_CD_WORKFLOW.md

File metadata and controls

534 lines (403 loc) · 15.1 KB
Raw

🔄 CI/CD Workflow - Complete Automation Flow

🎯 Overview

This document describes the complete automated workflow for ZPL2PDF, from development to publication.

📊 Complete Flow Diagram

Developer commits code
        ↓
    GitHub Push
        ↓
    ┌─────────────────────────────────────┐
    │   GitHub Actions CI/CD              │
    │   (Triggered automatically)         │
    └─────────────────────────────────────┘
        ↓
    ┌─────────────────────────────────────┐
    │   Step 1: Run Tests                 │
    │   - Unit tests (all platforms)      │
    │   - Integration tests               │
    │   - Code coverage                   │
    └─────────────────────────────────────┘
        ↓
    Tests Pass? ─── NO ──→ ❌ Stop (notify developer)
        ↓
       YES
        ↓
    ┌─────────────────────────────────────┐
    │   Step 2: Build All Platforms       │
    │   - Windows (x64, x86, ARM64)       │
    │   - Linux (x64, ARM64, ARM)         │
    │   - macOS (x64, ARM64)              │
    │   - Create archives (.zip/.tar.gz)  │
    │   - Generate checksums              │
    └─────────────────────────────────────┘
        ↓
    ┌─────────────────────────────────────┐
    │   Step 3: Build Docker Images       │
    │   - Alpine Linux (multi-arch)       │
    │   - Tag: latest, version, alpine    │
    └─────────────────────────────────────┘
        ↓
    ┌─────────────────────────────────────┐
    │   Step 4: Build Windows Installer   │
    │   - Inno Setup compilation          │
    │   - Multi-language support          │
    │   - Generate checksum               │
    └─────────────────────────────────────┘
        ↓
    Is this a Release Tag? ─── NO ──→ ✅ End (artifacts saved)
        ↓
       YES (v3.1.3, v3.1.3, etc.)
        ↓
    ┌─────────────────────────────────────┐
    │   Step 5: Publish Docker Images     │
    │   - Push to GitHub Container        │
    │     Registry (ghcr.io)              │
    │   - Push to Docker Hub              │
    │   - Multi-architecture support      │
    └─────────────────────────────────────┘
        ↓
    ┌─────────────────────────────────────┐
    │   Step 6: Create GitHub Release     │
    │   - Upload all platform builds      │
    │   - Upload Windows installer        │
    │   - Upload checksums                │
    │   - Generate release notes          │
    └─────────────────────────────────────┘
        ↓
    ┌─────────────────────────────────────┐
    │   Step 7: Create WinGet PR          │
    │   - Update winget manifest          │
    │   - Create PR to microsoft/winget   │
    │   - Automated submission            │
    └─────────────────────────────────────┘
        ↓
    ┌─────────────────────────────────────┐
    │   Step 8: Update Package Repos      │
    │   - Debian/Ubuntu (.deb)            │
    │   - Red Hat/CentOS (.rpm)           │
    │   - Homebrew (macOS/Linux)          │
    └─────────────────────────────────────┘
        ↓
    ✅ Complete! Users can download/install

🚀 Workflow Details

Trigger 1: Push to Main Branch

on:
  push:
    branches: [main]

What happens:

  1. ✅ Run all tests
  2. ✅ Build all platforms
  3. ✅ Save artifacts (for manual download)
  4. ❌ Does NOT publish (development build)

Purpose: Continuous Integration - ensure code quality

Trigger 2: Create Release (v3.1.3, v3.1.3, etc.)

on:
  release:
    types: [published]

What happens:

  1. ✅ Run all tests
  2. ✅ Build all platforms
  3. ✅ Build Docker images
  4. ✅ Build Windows installer
  5. ✅ Publish Docker → ghcr.io + Docker Hub
  6. ✅ Create GitHub Release → Upload all builds
  7. ✅ Create WinGet PR → Automated submission
  8. ✅ Update package repos → .deb, .rpm, Homebrew

Purpose: Continuous Deployment - full automated release

Trigger 3: Manual Workflow Dispatch

on:
  workflow_dispatch:

What happens:

  • Can be triggered manually from GitHub Actions UI
  • Useful for testing or custom builds
  • Follows same steps as push/release

📋 GitHub Actions Workflows

Current Workflows:

Workflow File Trigger Purpose
Docker Publish .github/workflows/docker-publish.yml ✅ Release Build & publish Docker images
WinGet Publish .github/workflows/winget-publish.yml ✅ Release Submit to microsoft/winget-pkgs
CI Tests .github/workflows/ci.yml ⏳ To create Run tests on every push
Release Build .github/workflows/release.yml ⏳ To create Build all platforms on release

🔧 Step-by-Step Process

Step 1: Developer Workflow

# 1. Developer makes changes
git checkout -b feature/new-feature
# ... code changes ...

# 2. Run tests locally
dotnet test

# 3. Commit and push
git add .
git commit -m "feat: add new feature"
git push origin feature/new-feature

# 4. Create Pull Request on GitHub
# → GitHub Actions runs tests automatically
# → Code review
# → Merge to main

Step 2: Automated Testing (On Every Push)

# .github/workflows/ci.yml (TO CREATE)
name: CI Tests

on:
  push:
    branches: [main, develop]
  pull_request:

jobs:
  test:
    strategy:
      matrix:
        os: [windows-latest, ubuntu-latest, macos-latest]
    
    runs-on: ${{ matrix.os }}
    
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '9.0.x'
      
      - name: Restore dependencies
        run: dotnet restore
      
      - name: Build
        run: dotnet build --no-restore
      
      - name: Test
        run: dotnet test --no-build --verbosity normal

Result: ✅ or ❌ Prevents broken code from being merged

Step 3: Create Release

# 1. Update version in files
# - ZPL2PDF.csproj
# - installer/ZPL2PDF-Setup.iss
# - CHANGELOG.md

# 2. Commit version bump
git add .
git commit -m "chore: bump version to 2.1.0"
git push

# 3. Create Git tag
git tag -a v3.1.3 -m "Release version 3.1.3"
git push origin v3.1.3

# 4. Create GitHub Release
# - Go to: https://github.com/brunoleocam/ZPL2PDF/releases/new
# - Select tag: v3.1.3
# - Write release notes
# - Click "Publish release"

# 5. GitHub Actions automatically:
#    ✅ Runs all tests
#    ✅ Builds all platforms
#    ✅ Builds Docker images
#    ✅ Publishes to Docker Hub + GitHub Registry
#    ✅ Uploads artifacts to GitHub Release
#    ✅ Creates WinGet PR

Step 4: Automated Docker Publishing

When you create a release, Docker workflow automatically:

# .github/workflows/docker-publish.yml (ALREADY EXISTS)

1. Log in to GitHub Container Registry (ghcr.io)
   - Uses: secrets.GITHUB_TOKEN (automatic)

2. Log in to Docker Hub
   - Uses: secrets.DOCKERHUB_USERNAME
   - Uses: secrets.DOCKERHUB_TOKEN

3. Build multi-architecture image
   - Platforms: linux/amd64, linux/arm64
   - Base: Alpine Linux (optimized)

4. Tag image with multiple tags:
   - latest
   - 2.1.0 (version)
   - 2.1 (major.minor)
   - 2 (major)
   - alpine (base image)

5. Push to both registries simultaneously:
   - ghcr.io/brunoleocam/zpl2pdf:2.1.0
   - brunoleocam/zpl2pdf:2.1.0

Result: Users can docker pull brunoleocam/zpl2pdf:latest

Step 5: Automated Windows Installer

# .github/workflows/release.yml (TO CREATE)

1. Build all Windows platforms
   - win-x64, win-x86, win-arm64

2. Extract win-x64 for installer

3. Compile Inno Setup script
   - Uses: installer/ZPL2PDF-Setup.iss
   - Output: ZPL2PDF-Setup-2.1.0.exe

4. Calculate SHA256 checksum

5. Upload to GitHub Release
   - ZPL2PDF-Setup-2.1.0.exe
   - ZPL2PDF-Setup-2.1.0.exe.sha256

Step 6: Automated WinGet Update

# .github/workflows/winget-publish.yml (CREATED)

1. Download installer from GitHub Release
   - URL: github.com/brunoleocam/ZPL2PDF/releases/download/v3.1.3/ZPL2PDF-Setup-3.0.3.exe

2. Calculate SHA256 hash automatically

3. Update manifest files (4 files):
   - brunoleocam.ZPL2PDF.yaml
   - brunoleocam.ZPL2PDF.installer.yaml
   - brunoleocam.ZPL2PDF.locale.en-US.yaml
   - brunoleocam.ZPL2PDF.locale.pt-BR.yaml

4. Fork/update brunoleocam/winget-pkgs

5. Create branch: brunoleocam.ZPL2PDF-2.1.0

6. Copy manifests to: manifests/b/brunoleocam/ZPL2PDF/2.1.0/

7. Create Pull Request to microsoft/winget-pkgs
   - Title: "brunoleocam.ZPL2PDF version 3.1.3"
   - Body: Auto-generated with release notes

Result: WinGet package updated after PR approval (~1-7 days)

🎯 Manual vs Automated

What You Do Manually:

Action Frequency Time
Write code Daily -
Run local tests Per feature 1 min
Create Git tag Per release 30 sec
Create GitHub Release Per release 2 min
TOTAL PER RELEASE - ~3 minutes

What GitHub Actions Does Automatically:

Action Time Status
Run tests (all platforms) 5 min ✅ Auto
Build 8 platforms 15 min ✅ Auto
Build Docker images 5 min ✅ Auto
Publish Docker (2 registries) 10 min ✅ Auto
Build Windows installer 2 min ✅ Auto
Upload to GitHub Release 5 min ✅ Auto
Create WinGet PR 2 min ✅ Auto
TOTAL ~45 minutes ✅ AUTOMATED

You save: ~40 minutes per release! ✅

📝 Versioning Strategy

Semantic Versioning (SemVer):

MAJOR.MINOR.PATCH
  2  .  1  .  3

Major: Breaking changes (2.0.0 → 3.0.0)
Minor: New features (2.0.0 → 2.1.0)
Patch: Bug fixes (2.1.0 → 2.1.1)

When to Release:

Change Type Version Bump Example
Bug fix Patch 2.0.0 → 2.0.1
New feature Minor 2.0.1 → 2.1.0
Breaking change Major 2.1.0 → 3.0.0

🔐 Required Secrets

Configure these in GitHub Settings → Secrets:

Secret Purpose How to get
DOCKERHUB_USERNAME Docker Hub login Your Docker Hub username
DOCKERHUB_TOKEN Docker Hub password https://hub.docker.com/settings/security
GITHUB_TOKEN GitHub API Automatic (provided by GitHub)

✅ Testing the Workflow

Test Before Release:

# 1. Create test tag (doesn't trigger release)
git tag -a test-v3.1.3 -m "Test release"
git push origin test-v3.1.3

# 2. Manually trigger workflow
# Go to: https://github.com/brunoleocam/ZPL2PDF/actions
# Select: "Docker Build and Publish"
# Click: "Run workflow"

Validate After Release:

# 1. Check Docker Hub
docker pull brunoleocam/zpl2pdf:2.0.0

# 2. Check GitHub Container Registry  
docker pull ghcr.io/brunoleocam/zpl2pdf:2.0.0

# 3. Check GitHub Release
# https://github.com/brunoleocam/ZPL2PDF/releases

# 4. Check WinGet PR
# https://github.com/microsoft/winget-pkgs/pulls?q=is:pr+ZPL2PDF

🐛 Troubleshooting

Tests Fail:

  • Check logs in GitHub Actions
  • Fix issues locally
  • Push fix and retry

Docker Build Fails:

  • Check Dockerfile syntax
  • Verify secrets are configured
  • Check Docker Hub quota

Installer Build Fails:

  • Verify build artifacts exist
  • Check Inno Setup script
  • Validate file paths

WinGet PR Fails:

  • Check manifest syntax
  • Verify SHA256 matches
  • Ensure version format is correct

📚 Files Involved in CI/CD

Configuration Files:

.github/workflows/
├── docker-publish.yml     ✅ EXISTS (Docker automation)
├── winget-publish.yml     ✅ EXISTS (WinGet automation)
├── ci.yml                 ⏳ TO CREATE (Test automation)
└── release.yml            ⏳ TO CREATE (Build automation)

scripts/
├── build-all-platforms.ps1  ✅ EXISTS
├── build-all-platforms.sh   ✅ EXISTS
├── release.ps1              ✅ EXISTS
└── release.sh               ✅ EXISTS

installer/
├── ZPL2PDF-Setup.iss        ✅ EXISTS
└── build-installer.ps1      ✅ EXISTS

Dockerfile                   ✅ EXISTS (Alpine optimized)
docker-compose.yml           ✅ EXISTS
winget-manifest.yaml         ⏳ TO VALIDATE

🎯 Next Steps to Complete Automation

  1. ✅ Docker Publish - Already configured
  2. ✅ WinGet Publish - Already configured
  3. ⏳ CI Tests - Create .github/workflows/ci.yml
  4. ⏳ Release Build - Create .github/workflows/release.yml

🌍 Distribution Channels

After automated workflow, ZPL2PDF is available on:

Channel URL Install Command
GitHub Releases Releases Manual download
GitHub Container ghcr.io docker pull ghcr.io/brunoleocam/zpl2pdf
Docker Hub Docker Hub docker pull brunoleocam/zpl2pdf
WinGet Microsoft Store winget install brunoleocam.ZPL2PDF
APT (future) PPA apt install zpl2pdf
YUM (future) RPM repo yum install zpl2pdf
Homebrew (future) Brew tap brew install zpl2pdf

✅ Benefits of This Workflow

  1. ✅ Consistency - Same build process every time
  2. ✅ Quality - Tests before every release
  3. ✅ Speed - 45 minutes automated vs hours manual
  4. ✅ Reliability - No human error
  5. ✅ Multi-platform - All platforms built simultaneously
  6. ✅ Documentation - Release notes automated
  7. ✅ Distribution - Multiple channels updated

This is the industry-standard CI/CD approach used by professional projects! 🚀