🔧 CI/CD Cheat Sheet¶

Quick reference for AudioLab CI/CD operations

GitHub Actions Workflows¶

Trigger Workflows Manually¶

# Via GitHub CLI
gh workflow run ci.yml
gh workflow run benchmark.yml
gh workflow run security-scan.yml

# Via GitHub UI
# Go to Actions → Select workflow → Run workflow

Monitor Workflow Status¶

# List recent runs
gh run list

# Watch specific run
gh run watch

# View logs
gh run view <run-id> --log

# Download artifacts
gh run download <run-id>

Cancel Running Workflows¶

# Cancel specific run
gh run cancel <run-id>

# Cancel all runs for a workflow
gh run list --workflow=ci.yml | awk '{print $7}' | xargs -I {} gh run cancel {}

Local CI Simulation¶

Run Full CI Locally¶

# Windows
.\scripts\local-ci-check.ps1

# macOS/Linux
./scripts/local-ci-check.sh

Manual Steps¶

# 1. Format check
clang-format --dry-run --Werror src/**/*.cpp include/**/*.hpp

# 2. Build all configurations
cmake -B build-debug -DCMAKE_BUILD_TYPE=Debug
cmake --build build-debug --parallel

cmake -B build-release -DCMAKE_BUILD_TYPE=Release
cmake --build build-release --parallel

# 3. Run tests
ctest --test-dir build-debug --output-on-failure
ctest --test-dir build-release --output-on-failure

# 4. Static analysis (optional)
cppcheck --enable=all src/
clang-tidy src/**/*.cpp

Workflow Files¶

Main Workflows¶

File	Trigger	Duration	Purpose
`ci.yml`	Push/PR	~12 min	Main CI pipeline
`test-suite.yml`	Push	~10 min	Comprehensive tests
`code-quality.yml`	PR	~5 min	Linting, formatting
`benchmark.yml`	Manual	~15 min	Performance tests
`security-scan.yml`	Daily	~8 min	Dependency audit
`release.yml`	Tag push	~20 min	Build & publish

Workflow Locations¶

.github/workflows/
├── ci.yml                 ← Main CI
├── test-suite.yml         ← Testing
├── code-quality.yml       ← Quality gates
├── benchmark.yml          ← Performance
├── security-scan.yml      ← Security
├── release.yml            ← Releases
└── README.md              ← Workflow docs

Common Tasks¶

Skip CI for Commit¶

# Add [skip ci] to commit message
git commit -m "Update docs [skip ci]"
git push

Re-run Failed Jobs¶

# Via GitHub CLI
gh run rerun <run-id>

# Via GitHub UI
# Go to Actions → Failed run → Re-run jobs → Re-run failed jobs

Add New Workflow¶

# .github/workflows/my-workflow.yml
name: My Custom Workflow

on:
  push:
    branches: [feature/**]

jobs:
  custom-job:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run custom script
        run: ./scripts/my-script.sh

Build Matrix¶

Default Matrix (6 jobs)¶

Windows × Debug
Windows × Release
macOS   × Debug
macOS   × Release
Linux   × Debug
Linux   × Release

Add New Platform¶

# In ci.yml, under matrix.include:
- os: Linux-ARM64
  runner: ubuntu-22.04-arm
  config: Release
  triplet: arm64-linux
  preset: linux-arm64-release

Add Sanitizer Build¶

- os: Linux-Sanitizers
  runner: ubuntu-22.04
  config: Debug
  cmake_flags: -DENABLE_ASAN=ON -DENABLE_UBSAN=ON

Caching¶

View Cache Usage¶

# Via GitHub CLI
gh api /repos/:owner/:repo/actions/caches

# Via GitHub UI
# Settings → Actions → Caches

Clear Cache¶

# Delete specific cache
gh cache delete <cache-id>

# Delete all caches for a branch
gh cache list --ref refs/heads/main | cut -f1 | xargs -I {} gh cache delete {}

Cache Keys¶

# vcpkg dependencies
key: vcpkg-${{ runner.os }}-${{ hashFiles('vcpkg.json') }}

# CMake build
key: cmake-${{ runner.os }}-${{ matrix.config }}-${{ github.sha }}

# ccache (Linux/macOS)
key: ccache-${{ runner.os }}-${{ github.run_id }}

Artifacts¶

Download Artifacts¶

# Via GitHub CLI
gh run download <run-id>

# Download specific artifact
gh run download <run-id> -n windows-release-binaries

# Via GitHub UI
# Actions → Workflow run → Artifacts section

Upload Custom Artifacts¶

- name: Upload custom artifact
  uses: actions/upload-artifact@v4
  with:
    name: my-artifact
    path: path/to/files
    retention-days: 7

Secrets Management¶

Add Secret¶

# Via GitHub CLI
gh secret set MY_SECRET < secret.txt

# Via GitHub UI
# Settings → Secrets → Actions → New repository secret

Use Secret in Workflow¶

steps:
  - name: Use secret
    env:
      MY_SECRET: ${{ secrets.MY_SECRET }}
    run: echo "Secret value: $MY_SECRET"

Common Secrets¶

Secret	Purpose
`CODECOV_TOKEN`	Upload coverage reports
`RELEASE_TOKEN`	Publish GitHub releases
`DISCORD_WEBHOOK`	Send notifications
`AWS_ACCESS_KEY_ID`	Deploy to AWS

Branch Protection¶

Enable Required Checks¶

# Via GitHub CLI
gh api -X PUT /repos/:owner/:repo/branches/main/protection \
  -f required_status_checks='{"strict":true,"contexts":["build-and-test"]}'

# Via GitHub UI
# Settings → Branches → Add rule
# ☑ Require status checks to pass
# ☑ build-and-test (Windows - Debug)
# ☑ build-and-test (macOS - Release)
# etc.

Debugging Failed CI¶

View Logs¶

# Via CLI
gh run view <run-id> --log

# Filter by job
gh run view <run-id> --job=<job-id> --log

# Download logs
gh run view <run-id> --log > ci-logs.txt

Enable Debug Logging¶

# Add to workflow
env:
  ACTIONS_STEP_DEBUG: true
  ACTIONS_RUNNER_DEBUG: true

SSH into Runner (Advanced)¶

# Add step to workflow
- name: Setup tmate session
  uses: mxschmitt/action-tmate@v3
  if: failure()  # Only on failure

Performance Optimization¶

Reduce CI Time¶

Use caching (vcpkg, CMake, ccache)
Limit matrix (remove unnecessary combinations)
Skip non-code changes (use paths-ignore)
Parallel jobs (default: automatic)
Use prebuilt containers (Docker with dependencies)

Example: Selective Triggering¶

on:
  push:
    paths:
      - 'src/**'
      - 'include/**'
      - 'tests/**'
      - 'CMakeLists.txt'
    paths-ignore:
      - '**/*.md'
      - 'docs/**'

Status Badges¶

Add to README¶

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

<!-- Test Coverage -->
![Coverage](https://codecov.io/gh/user/repo/branch/main/graph/badge.svg)

<!-- Release -->
![Release](https://img.shields.io/github/v/release/user/repo)

Custom Badge¶

![Custom](https://img.shields.io/endpoint?url=https://your-api.com/badge.json)

Notifications¶

Discord Webhook¶

- name: Notify Discord
  if: failure()
  env:
    DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
  run: |
    curl -X POST "$DISCORD_WEBHOOK" \
      -H "Content-Type: application/json" \
      -d "{\"content\":\"CI failed: ${{ github.ref }}\"}"

Slack Webhook¶

- name: Notify Slack
  uses: 8398a7/action-slack@v3
  with:
    status: ${{ job.status }}
    webhook_url: ${{ secrets.SLACK_WEBHOOK }}
  if: always()

Workflow Syntax Reference¶

Basic Structure¶

name: Workflow Name
on: [push, pull_request]
jobs:
  job-name:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Step name
        run: echo "Hello"

Conditional Execution¶

# Run only on main branch
if: github.ref == 'refs/heads/main'

# Run only on PR
if: github.event_name == 'pull_request'

# Run only on tag
if: startsWith(github.ref, 'refs/tags/')

# Run on failure
if: failure()

# Run always (even on failure)
if: always()

Matrix Strategy¶

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest, macos-latest]
    config: [Debug, Release]
  fail-fast: false  # Continue other jobs on failure

Quick Commands¶

# Trigger workflow
gh workflow run ci.yml

# Watch latest run
gh run watch

# Cancel run
gh run cancel <run-id>

# Download artifacts
gh run download <run-id>

# View workflow file
gh workflow view ci.yml

# List workflows
gh workflow list

# Enable/disable workflow
gh workflow enable ci.yml
gh workflow disable ci.yml

Resources¶

README.md - Full CI/CD documentation
QUICK_START.md - Setup guide
GitHub Actions Docs - Official documentation
Workflow Syntax - YAML reference

Master these commands for efficient CI/CD management! 🚀