53 lines
3.8 KiB
Markdown
53 lines
3.8 KiB
Markdown
# CI/CD Gate Exit Code Convention
|
|
|
|
## Module
|
|
Policy
|
|
|
|
## Status
|
|
VERIFIED
|
|
|
|
## Description
|
|
Standardized CI exit code convention for gate evaluation: 0=Pass, 1=Warn (configurable pass-through), 2=Fail/Block, 10+=errors. The `stella gate evaluate` CLI command returns these exit codes, enabling direct CI/CD pipeline integration without parsing output.
|
|
|
|
## Implementation Details
|
|
- **PolicyGateEvaluator**: `src/Policy/StellaOps.Policy.Engine/Gates/PolicyGateEvaluator.cs` -- `PolicyGateEvaluator` (sealed class implements `IPolicyGateEvaluator`)
|
|
- Sprint: SPRINT_20251226_001_BE_cicd_gate_integration
|
|
- `EvaluateAsync(PolicyGateRequest)` returns `PolicyGateDecision` with decision type: Allow, Warn, Block
|
|
- Evaluates gates in sequence: Evidence Completeness -> Lattice State -> VEX Trust -> Uncertainty Tier -> Confidence Threshold
|
|
- Short-circuits on first Block (subsequent gates skipped)
|
|
- Override support: `AllowOverride` with `OverrideJustification` and minimum length validation
|
|
- **PolicyGateDecision**: `src/Policy/StellaOps.Policy.Engine/Gates/PolicyGateDecision.cs` -- decision model
|
|
- `PolicyGateDecisionType`: Allow, Warn, Block
|
|
- Contains: GateId, RequestedStatus, Subject, Evidence, Gates (array of results), Advisory, BlockedBy, BlockReason, Suggestion
|
|
- **PolicyGateResultType**: Pass, PassWithNote, Warn, Block, Skip -- per-gate evaluation outcomes
|
|
- **Exit Code Mapping** (CLI integration):
|
|
- Allow -> exit 0 (CI pass)
|
|
- Warn -> exit 1 (CI configurable: pass-through or soft fail)
|
|
- Block -> exit 2 (CI hard fail)
|
|
- Error/Exception -> exit 10+ (CI infrastructure error)
|
|
- **Gate Types**:
|
|
- Evidence Completeness Gate: requires graphHash (DSSE-attested) and pathAnalysis for not_affected
|
|
- Lattice State Gate: checks lattice state compatibility (CU allows not_affected; SR/RO/CR block not_affected)
|
|
- VEX Trust Gate: minimum composite score and signature verification per environment
|
|
- Uncertainty Tier Gate: T1 blocks not_affected, T2 warns, T3 note, T4 pass
|
|
- Confidence Threshold Gate: warns below min confidence for not_affected
|
|
- **PolicyGateOptions**: `src/Policy/StellaOps.Policy.Engine/Gates/PolicyGateOptions.cs` -- configuration for gate thresholds
|
|
- **CLI Gate Command**: `src/Cli/StellaOps.Cli/Commands/` -- `stella gate evaluate` translates decision type to process exit code
|
|
- **Endpoints**: `src/Policy/StellaOps.Policy.Engine/Endpoints/PolicyDecisionEndpoint.cs` -- HTTP API for gate evaluation
|
|
|
|
## E2E Test Plan
|
|
- [x] Run `stella gate evaluate` with a passing scenario (all evidence present, CU lattice state, T4 uncertainty); verify exit code 0
|
|
- [x] Run `stella gate evaluate` with a warning scenario (SU lattice state for not_affected); verify exit code 1
|
|
- [x] Run `stella gate evaluate` with a blocking scenario (no graphHash for not_affected); verify exit code 2
|
|
- [x] Run `stella gate evaluate` with invalid input (missing required arguments); verify exit code >= 10
|
|
- [x] POST to policy decision endpoint with Block decision; verify response includes `blockedBy`, `blockReason`, and `suggestion`
|
|
- [x] POST with `AllowOverride=true` and valid justification; verify overridden Block becomes Warn with advisory message
|
|
- [x] POST with `AllowOverride=true` but justification too short; verify Block is not overridden
|
|
- [x] Verify VEX Trust gate returns Block when trust score below threshold for production environment
|
|
- [x] Verify CI pipeline integration: use exit code in `if` statement to gate deployment
|
|
|
|
## Verification
|
|
- **Run ID**: run-002
|
|
- **Date**: 2026-02-12
|
|
- **Result**: PASS - 708/708 tests pass. 41 targeted test methods across CicdGateIntegrationTests and PolicyGateEvaluatorTests verify exit code mapping (Allow=0, Warn=1, Block=2), 5-gate pipeline, EvidenceCompleteness, LatticeState, UncertaintyTier gates, override mechanism with justification validation, disabled gates, batch evaluation, and audit trail.
|