CI Pipeline Implementation Spec

Objective

Translate policy/checklist into an implementable CI pipeline.

Platform Strategy

Use one canonical gate model with two platform variants: - GitHub Actions: governance/ci_workflow_github_actions.yaml - GitLab CI: governance/ci_workflow_gitlab_ci.yaml

Select one based on repository host; keep gate logic identical.

Reusable Execution Scripts (Portability Requirement)

• Keep executable job logic in scripts/ci/*.sh.
• CI workflow files (.gitlab-ci.yml or GitHub Actions YAML) should only orchestrate stages/jobs and call these scripts.
• When moving between GitLab and GitHub, reuse the same scripts/ci commands and only adapt runner syntax and secret wiring.

Required Tools

• OpenAPI validator + Spectral
• AsyncAPI validator
• API diff checker for breaking changes
• ReviewGuard
• Policy check runner for governance/production_enforcement_policy.yaml
• Test runner(s)
• Security scanners (SAST/dependency/secret/container)

Pipeline Jobs

1. contracts_validate
2. contracts_breaking_change
3. build_and_unit_test
4. integration_and_contract_tests
5. security_scans
6. sdk_codegen_smoke
7. migration_validation
8. package_and_attest
9. deploy_staging
10. promote_prod (manual approval)

Migration Validation Requirements

migration_validation must verify both schema creation and deploy-safe forward application:

• fresh apply:
• start a disposable PostgreSQL instance
• apply current doc/architecture/db_schema_v1.sql
• fail on any DDL error
• incremental apply:
• materialize the previous committed doc/architecture/db_schema_v1.sql
• apply that previous schema to a disposable PostgreSQL instance
• apply the current schema on top
• fail on any forward-only ordering or additive-compatibility error

This gate exists to catch deploy regressions that a clean reset cannot see, such as: - creating an index before the referenced column exists on older environments - adding a foreign key before the referenced table/column exists - assuming a fresh-table definition when deploys actually run against an older live table

The reusable implementation lives in scripts/ci/migration_validation.sh, with the local operator entrypoint exposed as make db-migration-smoke.

Execution Tier Model

The implementation must expose three execution tiers:

1. fast
2. default for ordinary pushes
3. always-on baseline:
4. contract validation
5. build/unit tests
6. codegen smoke

7. baseline security scans

8. medium

9. automatically selected for workflow-sensitive file changes
10. typical triggers:
11. packages/web/**
12. doc/operations/local-dev/**
13. browser/auth/runtime smoke scripts
14. adds:
15. browser e2e
16. local-dev parity checks

17. targeted integration smokes

18. heavy

19. schedule-driven or explicit deploy intent
20. adds:
21. image publish
22. environment deploy
23. remote validation
24. rollback-capable checks

Selection must be automatic: - use rules:changes to map file changes to medium-tier jobs - use branch/source rules to map scheduled or deployment pipelines to heavy-tier jobs - do not require developers to remember which validation tier to invoke manually

Blocking Rules

• Jobs 1-8 must pass before staging deploy.
• Promotion to prod requires manual approval + security signoff for high-risk changes.
• Heavy-tier deploy jobs must not block ordinary push pipelines unless the pipeline source or file changes explicitly require them.

Contract Job Requirements

• Validate doc/api/openapi.draft.yaml
• Lint doc/api/openapi.draft.yaml with doc/governance/openapi.spectral.yaml
• Validate doc/api/asyncapi.draft.yaml
• Enforce contract invariants in doc/governance/Contract_Invariant_Gates.md
• Enforce applicable controls from doc/governance/production_enforcement_policy.yaml
• Fail on undeclared breaking change

PR Gate Requirements

• ReviewGuard policy pass
• Compatibility note for contract changes
• ADR reference for architecture-impacting changes

Minimum Artifacts Per Run

• Test reports
• Contract validation reports
• Security scan reports
• SBOM + provenance attestation