CI/CD Concepts

Continuous integration and deployment concepts, local verification, artifact management, and rollback strategies.

CI/CD Concepts

The pipeline stages — build, test, deploy

Source → Build → Test → Stage → Deploy
  │       │       │       │       │
  │       │       │       │       └─ Production release
  │       │       │       └─ Pre-production validation
  │       │       └─ Unit, integration, security tests
  │       └─ Compile, bundle, generate artifacts
  └─ Push, PR, tag, schedule trigger

Continuous Integration vs Continuous Deployment

CI  = every commit builds + tests automatically
CD  = every passing commit deploys automatically (to staging or production)

CI catches bugs early. CD eliminates manual release bottlenecks.

Build Verification

Local build check before pushing — the domus-captures pattern

# Build and check for warnings/errors
make 2>&1 | grep -E "WARN|ERROR"

# If clean, push
git push origin main

ShellCheck — lint bash scripts before they reach CI

# Check a single script
shellcheck scripts/backup.sh

# Check all scripts recursively
find scripts/ -name '*.sh' -exec shellcheck {} +

# Specific checks — disable false positives
shellcheck -e SC2034,SC2086 script.sh

Python linting — catch issues locally

# Type checking
mypy src/

# Linting
ruff check src/

# Formatting
ruff format --check src/

Artifact Management

Build once, deploy many — the artifact pattern

# Build produces an artifact
npx antora antora-playbook.yml
# Artifact: build/site/

# The same artifact deploys to staging AND production
# Never rebuild between environments

Versioned artifacts — tag-based releases

# Create a release from a tag
git tag -a v1.2.0 -m "Release 1.2.0"
git push origin v1.2.0

# GitHub CLI — create release with artifacts
gh release create v1.2.0 ./build/app.tar.gz --title "v1.2.0" --notes "Bug fixes"

Environment Promotion

Staging to production — the promotion pattern

# Deploy to staging (automatic on PR merge)
# Validate in staging
# Promote to production (manual approval or automatic)

# With gh CLI — check deployment status
gh run list --workflow=deploy.yml --limit 5

Feature flags — decouple deploy from release

Deploy: code reaches production servers
Release: feature becomes visible to users

Deploy frequently. Release when ready.
Feature flags let you deploy unreleased code safely.

Domus CI/CD Architecture

Hub-and-spoke deployment — no CI workflow needed in spokes

Spoke repos (domus-captures, domus-infra-ops, ...)
    → push to GitHub
    → Cloudflare Pages auto-builds
    → https://docs.domusdigitalis.dev

Push domus-docs hub only when changing:
    - antora-playbook.yml
    - ui-bundle.zip
    - Hub-only content

Pre-push validation — the local CI equivalent

#!/bin/bash
# .git/hooks/pre-push or manual check
set -euo pipefail

echo "Running pre-push checks..."
make 2>&1 | grep -E "WARN|ERROR" && { echo "Build has warnings"; exit 1; }
echo "All checks passed"

Rollback Strategies

Git-based rollback — revert to a known-good commit

# Find the last good deploy
git log --oneline -10

# Revert the bad commit (creates a new commit)
git revert HEAD
git push origin main

# Nuclear option — force reset (destructive, last resort)
# git reset --hard <good-commit>
# git push --force origin main

git revert is always preferred. It preserves history and is safe for shared branches.