🚀 CI/CD Quick Start¶

Set up continuous integration for AudioLab in 5 steps

Prerequisites¶

✅ GitHub repository for AudioLab
✅ Admin access to repository settings
✅ Basic understanding of Git workflows

Step 1: Copy Workflow Files (2 minutes)¶

AudioLab provides production-ready GitHub Actions workflows.

Option A: Use Provided Workflows (Recommended)¶

# Copy workflows to your repository
cp -r ".github/workflows" "your-repo/.github/"

# Commit
git add .github/workflows
git commit -m "Add AudioLab CI/CD workflows"
git push

Option B: Use Templates¶

# Create workflows directory
mkdir -p .github/workflows

# Copy from templates
cp "2 - FOUNDATION/03_INFRA/03_06_ci_cd_automation/03_06_00_github_actions/ci.yml" \
   ".github/workflows/ci.yml"

cp "2 - FOUNDATION/03_INFRA/03_06_ci_cd_automation/03_06_00_github_actions/release.yml" \
   ".github/workflows/release.yml"

Expected result: .github/workflows/ directory with CI configuration

Step 2: Configure Repository Secrets (3 minutes)¶

Some workflows require secrets for authentication.

Required Secrets (Optional)¶

Secret	Used For	How to Get
`CODECOV_TOKEN`	Code coverage reports	codecov.io
`RELEASE_TOKEN`	Publishing releases	GitHub Settings → Developer → PAT

Setting Secrets¶

Go to your GitHub repository
Click Settings → Secrets and variables → Actions
Click New repository secret
Add each secret

Skip if not using: Workflows will run without these, but some features disabled.

Step 3: Push and Trigger First CI Run (1 minute)¶

# Make a small change (e.g., edit README)
echo "# Testing CI" >> README.md

# Commit and push to trigger CI
git add README.md
git commit -m "Test CI pipeline"
git push origin main

Expected result: GitHub Actions starts building your code.

Step 4: Monitor CI Run (2-15 minutes)¶

Go to your GitHub repository
Click Actions tab
Click on the running workflow ("AudioLab CI")
Watch the build progress

What's happening:

┌──────────────────────────────────────┐
│  1. Checkout code                     │  30s
├──────────────────────────────────────┤
│  2. Setup build tools (CMake, vcpkg) │  2 min
├──────────────────────────────────────┤
│  3. Install dependencies (cached)     │  1 min
├──────────────────────────────────────┤
│  4. Configure with CMake              │  1 min
├──────────────────────────────────────┤
│  5. Build (Debug + Release)           │  5-8 min
├──────────────────────────────────────┤
│  6. Run tests                         │  1-2 min
├──────────────────────────────────────┤
│  7. Upload artifacts                  │  30s
└──────────────────────────────────────┘

Total: ~12-15 minutes (first run)
       ~8-10 minutes (cached)

Step 5: Fix Any Issues (Variable)¶

✅ Success - All checks passed¶

You'll see green checkmarks ✅. You're done!

❌ Failure - Some checks failed¶

Click on the failed job to see the error:

Common issues:

"CMakeLists.txt not found"
Fix: Ensure CMakeLists.txt is in repository root
Push the fix
"vcpkg package not found"
Fix: Add missing package to vcpkg.json

Example:

{
  "dependencies": [
    "catch2",
    "fftw3",
    "eigen3"
  ]
}

"Tests failed"
Fix: Tests must pass locally first
Run: ctest --output-on-failure
Fix failing tests, then push
"Formatting check failed"
Fix: Run clang-format
clang-format -i **/*.cpp **/*.hpp
Commit and push

For detailed troubleshooting, see TROUBLESHOOTING.md

Next Steps¶

Enable Branch Protection¶

Require CI to pass before merging:

Go to Settings → Branches
Click Add rule for main
Enable:
☑ Require status checks to pass
☑ Require branches to be up to date
Select: build-and-test
Save

Add Status Badge¶

Show CI status in your README:

![CI Status](https://github.com/your-user/your-repo/workflows/AudioLab%20CI/badge.svg)

Customize Workflows¶

See CI_CHEAT_SHEET.md for common customizations.

Available Workflows¶

AudioLab provides 11 production workflows:

Workflow	File	Trigger	Purpose
Main CI	`ci.yml`	Push/PR to main	Full build & test
Test Suite	`test-suite.yml`	Push	Comprehensive testing
Benchmarks	`benchmark.yml`	Manual	Performance testing
Code Quality	`code-quality.yml`	PR	Linting, formatting
Security	`security-scan.yml`	Daily	Dependency scanning
Release	`release.yml`	Tag push	Build & publish release

Most important: ci.yml - runs on every commit.

Understanding Build Matrix¶

The CI runs 6 parallel jobs:

Windows × Debug    → MSVC 2022, x64, VST3/AAX
Windows × Release  → Optimized build

macOS × Debug      → Clang 15, Universal Binary, VST3/AU
macOS × Release    → Optimized build

Linux × Debug      → GCC 12, x64, VST3/LV2
Linux × Release    → Optimized build

Total CI time: ~12-15 minutes (all jobs run in parallel)

Caching¶

AudioLab CI uses smart caching to speed up builds:

vcpkg dependencies: Cached per OS (rarely changes)
CMake build artifacts: Cached per configuration
ccache (Linux/macOS): Incremental compilation

Result: Second run ~40% faster (15 min → 8-10 min)

Monitoring Costs¶

GitHub Actions is free for public repos.

For private repos: - Free tier: 2,000 minutes/month - AudioLab usage: ~15 min/run × 3 platforms = 45 min/commit - Budget: ~44 commits/month on free tier

Optimization: Use paths-ignore to skip CI for docs-only changes.

Local CI Testing¶

Test before pushing to save CI minutes:

# Run local "CI" checks
./scripts/local-ci-check.sh

# Or manually:
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel
ctest --test-dir build --output-on-failure

Resources¶

README.md - Full CI/CD documentation
CI_CHEAT_SHEET.md - Common workflows and commands
TROUBLESHOOTING.md - Debug failed CI runs
.github/workflows/README.md - Workflow documentation

Quick Copy-Paste Setup¶

# 1. Copy workflows
cp -r .github/workflows ~/my-audiolab-project/.github/

# 2. Commit
cd ~/my-audiolab-project
git add .github/workflows
git commit -m "Add CI/CD workflows"

# 3. Push and trigger
git push origin main

# 4. Watch at:
# https://github.com/your-user/your-repo/actions

Your CI/CD is now running! 🎉

Every commit will automatically: - ✅ Build on Windows, macOS, Linux - ✅ Run all tests - ✅ Check code quality - ✅ Generate artifacts

No manual work required!