ci-templates

name	ci-templates
description	Use when setting up CI/CD pipelines. Teaches pipeline design principles and references platform-specific templates.

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.

Framework	Cache Path
PHP/Composer	vendor/
Node.js	node_modules/
Python	.venv/ or ~/.cache/pip

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

Platform	Template Location	Config File
GitLab CI	docs/ci-templates/gitlab/	.gitlab-ci.yml
GitHub Actions	docs/ci-templates/github/	.github/workflows/*.yml

Image Strategy

Option 1: Public Images (Recommended Start)

No setup required. Works everywhere.

Framework	Image	Notes
PHP	php:8.3-cli	Add extensions in before_script
Python	python:3.12	Add deps in before_script
Node	node:20	Works out of the box
Playwright	mcr.microsoft.com/playwright:latest	All browsers included
Security	aquasec/trivy:latest	Multi-language scanner

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.

Scanner	What It Checks	Image
composer audit	PHP dependencies	php:*
npm audit	Node dependencies	node:*
pip-audit	Python dependencies	python:*
Trivy	Everything + containers	aquasec/trivy
Gitleaks	Secrets in code	zricethezav/gitleaks

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:

Stack	GitLab	GitHub
Laravel/PHP	docs/ci-templates/gitlab/laravel.yml	docs/ci-templates/github/laravel.yml
Django/Python	docs/ci-templates/gitlab/django.yml	docs/ci-templates/github/django.yml
React/Node	docs/ci-templates/gitlab/react.yml	docs/ci-templates/github/react.yml
Full-Stack	docs/ci-templates/gitlab/fullstack.yml	docs/ci-templates/github/fullstack.yml

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