CI/CD Templates

Principles for designing fast, reliable CI/CD pipelines. Platform-specific templates in docs/ci-templates/.

When to Use

• Setting up a new CI/CD pipeline
• Optimizing slow pipelines
• Adding security scanning
• Migrating between CI platforms

Core Principles

1. Fail Fast

Run quick checks first. Don't waste 10 minutes building if linting fails in 10 seconds.

Stage Order:
1. Lint/Format (seconds)
2. Type Check (seconds)
3. Unit Tests (minutes)
4. Integration Tests (minutes)
5. Build (minutes)
6. E2E Tests (minutes)
7. Deploy (varies)

2. Cache Dependencies

Never re-download what you already have.

3. Parallelize Independent Jobs

Jobs that don't depend on each other should run simultaneously.

✓ Good: lint + unit-tests + type-check (parallel)
✗ Bad: lint → unit-tests → type-check (sequential)

4. Use Artifacts for Handoffs

Don't rebuild between stages. Pass build artifacts.

5. Default to Public Images

Use Docker Hub, GitHub Container Registry, or official images by default. Custom registries are an optimization, not a requirement.

Platform Support

Image Strategy

Option 1: Public Images (Recommended Start)

No setup required. Works everywhere.

Option 2: Custom Registry (Optimization)

For faster builds, pre-bake dependencies into custom images.

Configure in .claude/registry.json:

{
  "registry": "your-registry.example.com/images",
  "images": {
    "php": { "testing": "php:8.3-testing" },
    "node": { "base": "node:20-base" }
  }
}

See docs/registry-config.md for building custom images.

Security Scanning

Always include security scanning. Use allow_failure: true initially to avoid blocking deploys while you fix issues.

Quick Start

GitLab CI

# .gitlab-ci.yml - minimal working example
stages: [test]

test:
  image: node:20
  script:
    - npm ci
    - npm test
  cache:
    paths: [node_modules/]

GitHub Actions

# .github/workflows/test.yml - minimal working example
name: Test
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm test

Template Reference

Full templates for common stacks:

Checklist

When setting up a pipeline:

• Stages ordered by speed (fast first)
• Dependencies cached
• Independent jobs parallelized
• Artifacts passed between stages
• Security scanning included
• Works with public images (custom registry optional)

Common Mistakes

1. No caching → Slow builds, wasted bandwidth
2. Sequential everything → 20 min pipeline that could be 5 min
3. Hardcoded registry → Breaks for contributors
4. No security scanning → Vulnerabilities ship to prod
5. E2E tests blocking → Flaky tests block all deploys

Integration

These templates work with:

• /laravel, /python, /react commands
• /architect security for security scanning
• system-architect skill for infrastructure audits