dance-lessons-coach/scripts/cicd/README.md

CI/CD Scripts for DanceLessonsCoach

🚀 Quick Start for Contributors

You Only Need These Commands

# 1. Run tests (this is what matters most!)
go test ./...

# 2. Build binaries
./scripts/build.sh

# 3. Check formatting
go fmt ./...

# That's it! The CI/CD pipeline will handle the rest when you create a PR.

📖 Understanding the CI/CD Pipeline

What Happens Automatically

When you push code or create a PR, GitHub Actions runs:

1. Go CI/CD Pipeline (.gitea/workflows/go-ci-cd.yaml)

   • Builds all Go packages
   • Runs tests with coverage
   • Checks code formatting
   • Validates workflow structure

2. Docker Image Pipeline (.gitea/workflows/dockerimage.yaml)

   • Builds Docker image (on main branch only)
   • Publishes to Gitea Container Registry
   • Tags with version and commit SHA

When Does It Run?

Event	Go CI/CD	Docker Image
Push to main	✅ Yes	✅ Yes
Push to feature/*	✅ Yes	❌ No
Push to fix/*	✅ Yes	❌ No
Push to ci/*	✅ Yes	❌ No
Pull Request	✅ Yes	❌ No
Manual trigger	✅ Yes	✅ Yes

🧪 Local Testing Options

Option 1: Simple Validation (No Docker Required)

# Just run the essentials
./scripts/cicd/contributor-quickstart.sh

This checks:

• ✅ Go installation
• ✅ All tests pass
• ✅ Code formatting
• ✅ Go vet analysis
• ✅ Workflow structure

Option 2: Docker-Based Testing (Recommended)

# Test workflow compatibility with GitHub Actions
./scripts/cicd/test-act-local.sh

Requirements:

• Docker installed and running
• Internet connection (to pull images)

What it does:

• Validates YAML syntax
• Checks workflow structure
• Simulates GitHub Actions execution
• Tests both workflow files

Option 3: Full CI/CD Simulation

# Complete local simulation
./scripts/cicd/test-cicd-simple.sh

Requirements:

• Docker installed and running
• More time (pulls multiple images)

What it does:

• YAML linting
• YAML validation
• Workflow structure validation
• Simulates build job
• Runs actual Go tests in containers

🐳 Docker Setup Guide

For Windows Users

1. Install Docker Desktop

   • Download: https://www.docker.com/products/docker-desktop/
   • Enable WSL 2 backend (recommended)
   • Allocate at least 4GB RAM

2. Verify Installation

   docker --version
   docker run hello-world
   

For macOS Users

1. Install Docker Desktop

   • Download: https://www.docker.com/products/docker-desktop/
   • Grant necessary permissions

2. Verify Installation

   docker --version
   docker run hello-world
   

For Linux Users

1. Install Docker Engine

   # Ubuntu/Debian
   sudo apt-get update
   sudo apt-get install docker.io docker-compose
   sudo systemctl enable docker
   sudo systemctl start docker
   
   # Add user to docker group (avoid sudo)
   sudo usermod -aG docker $USER
   newgrp docker  # Reload group membership
   

2. Verify Installation

   docker --version
   docker run hello-world
   

🔧 Troubleshooting

Docker Permission Issues

Symptom: Got permission denied while trying to connect to the Docker daemon socket

Solution:

# Linux/macOS
sudo usermod -aG docker $USER
newgrp docker

# Windows
Right-click Docker Desktop → Settings → Resources → WSL Integration → Enable

Docker Not Running

Symptom: Cannot connect to the Docker daemon

Solution:

• Windows/macOS: Open Docker Desktop app
• Linux: sudo systemctl start docker

Network Issues

Symptom: Cannot pull Docker images

Solution:

# Check internet connection
ping google.com

# Try pulling manually first
docker pull mikefarah/yq:latest
docker pull pipelinecomponents/yamllint:latest

act Not Installed

Symptom: act not found in test-act-local.sh

Solution:

# Install act (optional - only needed for test-act-local.sh)
# macOS
brew install act

# Linux
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

# Windows (WSL)
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

📚 Script Reference

Script	Purpose	Docker Required?	act Required?
contributor-quickstart.sh	Basic validation	❌ No	❌ No
validate-workflow.sh	Workflow structure	❌ No	❌ No
test-act-local.sh	GitHub Actions compatibility	✅ Yes	✅ Yes
test-cicd-simple.sh	Full CI/CD simulation	✅ Yes	❌ No

🎯 Best Practices

Before Submitting a PR

1. Run tests locally

   go test ./...
   

2. Check formatting

   go fmt ./...
   

3. Build binaries

   ./scripts/build.sh
   

4. Validate workflows (optional)

   ./scripts/cicd/validate-workflow.sh
   

Working with the CI/CD Pipeline

• Don't worry about Docker images - The pipeline builds them automatically
• Focus on tests - If tests pass locally, they'll pass in CI/CD
• Check PR status - GitHub will show CI/CD results automatically
• Fix failures - If CI/CD fails, check the logs and fix issues

🔗 Useful Links

• GitHub Actions Docs: https://docs.github.com/en/actions
• Docker Docs: https://docs.docker.com/
• act GitHub: https://github.com/nektos/act
• DanceLessonsCoach CI/CD: See .gitea/workflows/ directory

💡 Pro Tips

Speed Up Local Testing

# Pull Docker images in advance
docker pull mikefarah/yq:latest
docker pull pipelinecomponents/yamllint:latest
docker pull node:16-buster-slim

Test Specific Workflows

# Test Go CI/CD workflow only
act -W .gitea/workflows/go-ci-cd.yaml

# Test Docker workflow only
act -W .gitea/workflows/dockerimage.yaml

Dry Run (No Execution)

# Check workflow syntax without running
echo 'm' | act -n -W .gitea/workflows/go-ci-cd.yaml

📞 Need Help?

If you're stuck with CI/CD setup:

1. Check this documentation - Most issues are covered here
2. Run contributor-quickstart.sh - It validates the essentials
3. Ask in the PR - We'll help you resolve any issues
4. Check CI/CD logs - GitHub shows detailed error messages

Remember: You don't need to run CI/CD locally to contribute! The pipeline runs automatically when you push code.