| 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
stages: [test]
test:
image: node:20
script:
- npm ci
- npm test
cache:
paths: [node_modules/]
GitHub Actions
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:
Common Mistakes
- No caching → Slow builds, wasted bandwidth
- Sequential everything → 20 min pipeline that could be 5 min
- Hardcoded registry → Breaks for contributors
- No security scanning → Vulnerabilities ship to prod
- E2E tests blocking → Flaky tests block all deploys
Integration
These templates work with:
/laravel, /python, /react commands/architect security for security scanningsystem-architect skill for infrastructure audits
