picpeak/CI_CD_STRATEGY.md

CI/CD Strategy for PicPeak

Overview

This document outlines the CI/CD strategy using both Gitea Actions and Drone CI to avoid conflicts and ensure proper versioning.

Pipeline Flow

1. Development & Testing (Gitea Actions)

• Trigger: Every push to main or develop branches
• File: .gitea/workflows/test.yml
• Purpose: Run tests, linting, and basic validation
• Actions:
  • Backend linting and tests
  • Frontend linting and build
  • Does NOT build Docker images

2. Version Management (Gitea Actions)

• Trigger: Push to main branch (excluding markdown files)
• File: .gitea/workflows/version-and-release.yml
• Purpose: Automatic version incrementing
• Actions:
  1. Reads current version from package.json
  2. Increments patch version (e.g., 1.0.0 → 1.0.1)
  3. Updates both backend and frontend package.json
  4. Commits the version change
  5. Creates a git tag (e.g., v1.0.1)
  6. Pushes changes and tag

3. Docker Image Building (Drone CI)

• Trigger:
  • Push to main or develop (builds with commit SHA)
  • New git tags (builds release versions)
• File: .drone.yml
• Purpose: Build and push Docker images
• Tags Created:
  • latest - Always points to newest build
  • {commit-sha} - Specific commit version
  • {branch}-latest - Latest for specific branch
  • v1.0.1 - Specific version (on tag trigger)

Why This Strategy?

1. Separation of Concerns:

   • Gitea Actions handles code quality and versioning
   • Drone CI handles Docker image building
   • No overlap or race conditions

2. Sequential Execution:

   • Version bump happens first
   • Tag creation triggers Drone
   • Docker images are built with correct version

3. Version Consistency:

   • Version in package.json matches git tag
   • Docker images are tagged with same version
   • No manual version management needed

Setup Requirements

1. Gitea Actions Runner: Must be configured and running
2. Drone CI: Must be connected to your Gitea instance
3. Secrets:
   • GITEA_TOKEN (optional, for pushing version commits)
   • Docker registry credentials in Drone

Version Numbering

• Format: MAJOR.MINOR.PATCH (e.g., 1.0.0)
• Automatic increments: PATCH version only
• Manual increments: Edit package.json for MAJOR/MINOR changes

Usage

1. Regular Development:

   git add .
   git commit -m "feat: add new feature"
   git push origin main
   

   • Tests run automatically
   • Version bumps to 1.0.1
   • Docker images built with v1.0.1 tag

2. Major/Minor Version Change:

   # Manually edit package.json files to 2.0.0
   git add .
   git commit -m "feat!: major release"
   git push origin main
   

3. Skip Version Bump:

   • Add [skip ci] to commit message
   • Or only change markdown files

Monitoring

• Gitea Actions: Check Actions tab in Gitea
• Drone CI: Check Drone dashboard
• Docker Registry: Verify images are pushed with correct tags

Troubleshooting

1. Version not incrementing:

   • Check Gitea Actions logs
   • Ensure runner has push permissions
   • Verify no [skip ci] in commit message

2. Docker images not building:

   • Check Drone CI webhook configuration
   • Verify Drone can see the repository
   • Check Docker registry credentials

3. Conflicts:

   • Never run both pipelines for same task
   • Use branch protection to prevent direct pushes
   • Always let automation handle versioning