🤖 feat: simplify CI/CD structure and add Docker workflow
Some checks failed
Some checks failed
- Rename ci-cd.yaml to go-ci-cd.yaml for clarity - Add dockerimage.yaml workflow for Docker builds - Create Dockerfile for production deployment - Add comprehensive CI/CD documentation - Create contributor-quickstart.sh for easy validation - Update all scripts to handle both workflow files - Fix event triggers to run on all relevant pushes - Remove redundant YAML syntax validation - Improve workflow validation for Arcodange conventions BREAKING CHANGE: ci-cd.yaml renamed to go-ci-cd.yaml See scripts/cicd/README.md for complete documentation. Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
This commit is contained in:
286
scripts/cicd/README.md
Normal file
286
scripts/cicd/README.md
Normal file
@@ -0,0 +1,286 @@
|
||||
# CI/CD Scripts for DanceLessonsCoach
|
||||
|
||||
## 🚀 Quick Start for Contributors
|
||||
|
||||
### You Only Need These Commands
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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**
|
||||
```powershell
|
||||
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**
|
||||
```bash
|
||||
docker --version
|
||||
docker run hello-world
|
||||
```
|
||||
|
||||
### For Linux Users
|
||||
|
||||
1. **Install Docker Engine**
|
||||
```bash
|
||||
# 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**
|
||||
```bash
|
||||
docker --version
|
||||
docker run hello-world
|
||||
```
|
||||
|
||||
## 🔧 Troubleshooting
|
||||
|
||||
### Docker Permission Issues
|
||||
|
||||
**Symptom:** `Got permission denied while trying to connect to the Docker daemon socket`
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
# 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**
|
||||
```bash
|
||||
go test ./...
|
||||
```
|
||||
|
||||
2. **Check formatting**
|
||||
```bash
|
||||
go fmt ./...
|
||||
```
|
||||
|
||||
3. **Build binaries**
|
||||
```bash
|
||||
./scripts/build.sh
|
||||
```
|
||||
|
||||
4. **Validate workflows** (optional)
|
||||
```bash
|
||||
./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
|
||||
|
||||
```bash
|
||||
# Pull Docker images in advance
|
||||
docker pull mikefarah/yq:latest
|
||||
docker pull pipelinecomponents/yamllint:latest
|
||||
docker pull node:16-buster-slim
|
||||
```
|
||||
|
||||
### Test Specific Workflows
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
Reference in New Issue
Block a user