dance-lessons-coach/documentation/local-ci-cd-testing.md

Local CI/CD Testing Guide

This guide explains how to test the CI/CD pipeline locally without requiring a Gitea instance.

Overview

The local CI/CD testing allows you to:

• Test the entire build process locally
• Simulate version bumping based on commit conventions
• Build Docker images with the correct version tags
• Test the container before pushing to production

Available Testing Methods

1. Interactive Local Testing Script

File: scripts/test-local-ci-cd.sh

What it does:

• Installs dependencies
• Generates Swagger documentation
• Runs compilation and tests
• Builds binaries
• Simulates version bumping
• Provides Docker build instructions
• Optionally builds and runs Docker container

Usage:

./scripts/test-local-ci-cd.sh

Features:

• Interactive prompts for Docker build and run
• Automatic endpoint testing
• Clear instructions for each step
• Version-aware Docker image tagging

2. Local CI/CD Workflow

File: .gitea/workflows/test-local-ci-cd.yaml

What it does:

• Simulates the CI/CD pipeline in a workflow format
• Provides detailed instructions for local Docker builds
• Shows version bump simulation
• Lists all test results

Usage: This workflow can be triggered manually or on test/feature branches.

3. Workflow Validation

File: scripts/cicd/validate-workflow.sh

What it does:

• Validates YAML syntax
• Checks required workflow fields
• Validates job structure
• Verifies Arcodange-specific configurations

Usage:

./scripts/cicd/validate-workflow.sh

Step-by-Step Local Testing

1. Run the Interactive Script

cd /Users/gabrielradureau/Work/Vibe/dance-lessons-coach
./scripts/test-local-ci-cd.sh

2. Follow the Prompts

The script will guide you through:

• Environment setup
• Dependency installation
• Code compilation and testing
• Binary building
• Version bump simulation
• Docker build options

3. Docker Testing (Optional)

If you choose to build the Docker image:

# Build with current version
docker build -t dance-lessons-coach:$CURRENT_VERSION .

# Tag as latest
docker tag dance-lessons-coach:$CURRENT_VERSION dance-lessons-coach:latest

# Check if port is available
./scripts/check-port.sh 8080 8081 8082

# Run the container (use available port)
docker run -d -p 8080:8080 --name dance-lessons-coach-test dance-lessons-coach:$CURRENT_VERSION
# Or use alternative port if 8080 is in use
docker run -d -p 8081:8080 --name dance-lessons-coach-test dance-lessons-coach:$CURRENT_VERSION

# Branch-specific naming (recommended for multiple branches)
BRANCH=$(git rev-parse --abbrev-ref HEAD | tr '/' '-')
docker run -d -p 8080:8080 --name "dance-lessons-coach-$BRANCH" dance-lessons-coach:$CURRENT_VERSION

Port Checking: The script automatically checks if port 8080 is available and suggests alternatives.

Container Management:

• Automatically removes existing containers with the same name
• Uses branch-based naming to avoid conflicts
• Supports multiple branch testing simultaneously

4. Test the Container

# Health check
curl http://localhost:8080/api/health

# Greet endpoint
curl http://localhost:8080/api/v1/greet/YourName

# Swagger UI
open http://localhost:8080/swagger/

5. Clean Up

# Stop and remove container (generic)
docker stop dance-lessons-coach-test
docker rm dance-lessons-coach-test

# Stop and remove branch-specific container
BRANCH=$(git rev-parse --abbrev-ref HEAD | tr '/' '-')
docker stop "dance-lessons-coach-$BRANCH"
docker rm "dance-lessons-coach-$BRANCH"

# Remove all test containers
docker stop $(docker ps -aq --filter "name=dance-lessons-coach")
docker rm $(docker ps -aq --filter "name=dance-lessons-coach")

# Remove images (optional)
docker rmi dance-lessons-coach:$CURRENT_VERSION
docker rmi dance-lessons-coach:latest

Cleanup Tips:

• Use docker ps -a to see all containers
• Use docker images to see all images
• Use docker system prune to clean up unused objects

Version Management

The local testing respects the same version conventions as the production CI/CD:

• feat: commits → MINOR version bump
• fix: commits → PATCH version bump
• BREAKING CHANGE: → MAJOR version bump
• Other commits → No automatic bump

Manual version bump:

# Bump patch version
./scripts/version-bump.sh patch

# Bump minor version  
./scripts/version-bump.sh minor

# Bump major version
./scripts/version-bump.sh major

Docker Build Optimization

The Dockerfile is optimized to:

• Only install swag if swagger.json doesn't exist
• Reuse existing swagger.json from CI/CD workflow
• Generate documentation only when needed

This means:

• Local builds: Will generate swagger docs if missing
• CI/CD builds: Will reuse existing swagger.json
• Production builds: Most efficient path

Testing Different Scenarios

Test Version Bumping

# Make a feature commit
git commit -m "feat: add new feature"
./scripts/test-local-ci-cd.sh  # Will show MINOR bump suggestion

# Make a fix commit
git commit -m "fix: resolve issue"
./scripts/test-local-ci-cd.sh  # Will show PATCH bump suggestion

Test Without Docker

# Run tests without Docker
./scripts/test-local-ci-cd.sh
# Answer 'n' when asked about Docker build

Test Specific Components

# Just build and test
go build ./...
go test ./... -cover

# Just generate swagger docs
cd pkg/server && go generate

# Just build binaries
./scripts/build.sh

# Check port availability
./scripts/check-port.sh 8080 8081 8082

Production Deployment

When you're ready to deploy:

1. Commit your changes with appropriate commit message
2. Push to main branch to trigger production CI/CD
3. Monitor the workflow in Gitea Actions
4. Verify the Docker image in Gitea Container Registry

# Example production deployment
git add .
git commit -m "feat: add new API endpoint"
git push origin main

Troubleshooting

Port Conflicts

# Check what's using port 8080
./scripts/check-port.sh 8080

# Find and kill process on port 8080
kill -9 $(lsof -ti :8080)

# Use alternative port
docker run -d -p 8081:8080 --name dance-lessons-coach-test dance-lessons-coach:$CURRENT_VERSION

Docker Build Issues

# Clean build
docker system prune -a --volumes
rm -rf pkg/server/docs/
./scripts/test-local-ci-cd.sh

Dependency Issues

# Clean and reinstall
go clean -cache
go mod tidy
./scripts/test-local-ci-cd.sh

Test Failures

# Run specific test
go test ./pkg/greet/ -v

# Run with race detector
go test ./... -race

Best Practices

1. Test locally first before pushing to CI/CD
2. Use commit conventions for automatic version bumping
3. Test Docker images before production deployment
4. Clean up containers after testing
5. Monitor CI/CD logs for any issues

Summary

The local CI/CD testing provides:

• ✅ Full build pipeline simulation
• ✅ Version-aware Docker builds
• ✅ Interactive testing experience
• ✅ Production-like environment
• ✅ Easy troubleshooting

Use these tools to ensure your changes work correctly before deploying to production!