CI/CD Pipeline

Status: Canonical (Draft) Last Updated: 2026-02-06 Owner: Engineering

Purpose

This document defines the Continuous Integration and Continuous Deployment (CI/CD) pipeline standards for CAIRL.

It establishes:

  • How code and documentation changes are validated
  • How environments are protected
  • How compliance, security, and data safety are enforced before deployment
  • What conditions MUST block a deployment

This document defines architectural guarantees. Implementation tooling may change, but guarantees MUST hold.

Scope

This pipeline applies to:

  • Application code
  • Database migrations
  • Infrastructure configuration
  • Documentation under /docs
  • All environments (dev, staging, production)

No deployment may bypass these rules.

Core CI/CD Principles (Invariants)

  1. Deployments are repeatable and deterministic.
  2. Unsafe changes fail fast and block promotion.
  3. Production is protected from unreviewed changes.
  4. Compliance and security checks are first-class.
  5. Documentation and code evolve together.

Environment Model

CAIRL uses three primary environments:

Development

  • Used for active feature development
  • May contain incomplete features
  • Uses non-production credentials
  • No real HIPAA data

Staging

  • Pre-production validation environment
  • Mirrors production configuration
  • Used for QA, UAT, and compliance verification
  • Limited, controlled test data only

Production

  • Serves real users
  • Handles regulated data
  • Subject to full compliance guarantees
  • Changes are tightly controlled

Environment promotion MUST be linear: dev → staging → production.

Source Control and Branching

  • All work occurs on feature branches
  • Pull requests are required for merges
  • Direct commits to protected branches are prohibited

Protected branches:

  • main (production)
  • staging

Required CI Checks (All Pull Requests)

The following checks MUST pass before merge:

Code Quality

  • Type checking
  • Linting
  • Build succeeds

Test Validation

  • Unit tests
  • Integration tests (where applicable)
  • RLS and authorization tests (if impacted)

Security and Compliance

  • Dependency vulnerability scanning
  • Secrets scanning
  • Migration safety checks

Documentation Validation

  • Documentation builds without error
  • No broken doc references
  • .new.md files are not referenced as canonical

Database Migration Controls

For changes involving Postgres:

  • Migrations MUST be reviewed
  • RLS MUST be enabled on new tables
  • RLS policies MUST be defined before exposure
  • Migrations MUST be reversible where feasible

Deployments MUST block if:

  • RLS is missing on user-owned or regulated tables
  • Service-role access is introduced improperly

Deployment Gates

Dev Deployment

  • Automated on merge to dev branch
  • No manual approval required

Staging Deployment

  • Automated on merge to staging
  • Requires passing all CI checks
  • Used for validation and sign-off

Production Deployment

  • Manual approval required
  • Requires successful staging deployment
  • Requires no outstanding critical alerts

Compliance and Safety Gates

Production deployments MUST be blocked if:

  • Retention or deletion jobs are failing
  • Abuse guardrails are disabled
  • Observability gaps are detected
  • HIPAA access logging is impaired
  • Provider integrations are unhealthy

Safety gates override release urgency.

Documentation as a Deployment Artifact

Documentation is treated as code.

Rules:

  • Specs and flows MUST exist before implementation
  • Contract changes require explicit review
  • Deployments MAY be blocked if docs are missing or inconsistent

Docs drift is considered a deployment risk.

Rollback Strategy

  • Deployments MUST be reversible
  • Database migrations MUST support rollback or forward-fix
  • Rollbacks MUST not violate retention or compliance rules

Rollback procedures MUST be documented.

Secrets and Configuration Management

  • Secrets are stored in secure environment stores
  • Secrets MUST NOT be committed
  • Environment separation is mandatory
  • Rotation procedures MUST be documented

Observability Integration

CI/CD MUST validate:

  • Logging pipelines are functional
  • Alerts are configured
  • Metrics collection is active

Deployments MUST fail if observability is broken.

Auditability

The pipeline MUST provide:

  • Deployment history
  • Change attribution
  • Approval records
  • Evidence for SOC 2 audits

Non-Negotiable Rules

  • No unchecked deployment to production.
  • No bypassing CI gates.
  • No schema changes without RLS.
  • No deployment without observability.
  • No drift between docs and code.

References

  • docs/governance/doc-authority.new.md
  • docs/architecture/system-overview.new.md
  • docs/architecture/observability-plan.new.md
  • docs/contracts/authz-and-roles.new.md
  • docs/contracts/rls-standard.new.md
  • docs/contracts/data-retention.new.md

End of Document