Skip to content

Latest commit

 

History

History
239 lines (166 loc) · 4.9 KB

rollouts.md

File metadata and controls

239 lines (166 loc) · 4.9 KB

Policy Rollout API

The rollout API provides controlled policy lifecycle management — from proposed plan to live policy with full audit trail.

Authentication

All endpoints require Authorization: Bearer <API_KEY> header or gitwire-session cookie.


Lifecycle

draft → validated → review_ready → approved → promoted
                                    ↘ rejected
   ↘ cancelled (from draft, validated, approved)
promoted → rolled_back

Terminal states: rolled_back, rejected, cancelled


POST /api/rollouts

Create a new rollout plan in draft state.

Request

{
  "repo": "Octo-Lex/GitWire",
  "proposed_config": {
    "dry_run": true,
    "pillars": {
      "triage": { "enabled": true }
    }
  },
  "created_by": "nalajmah"
}

Response (201)

Returns the created plan with redacted normalized config.


GET /api/rollouts

List rollout plans with optional filters.

Query parameters

Param Type Default Description
repo string — Filter by repo full_name
status string — Filter by lifecycle status
created_by string — Filter by creator
limit number 50 Max results (capped at 200)
offset number 0 Pagination offset

Response

{
  "data": [...],
  "total": 5
}

GET /api/rollouts/:id

Get a single rollout plan by ID.

Returns full plan with all metadata, evidence, and config snapshots (redacted).


PATCH /api/rollouts/:id/evidence

Attach evidence summaries to a plan. Only allowed in draft or validated state.

Request

{
  "validation_result": { "valid": true, ... },
  "simulation_summary": { "would_act": 4, ... },
  "diff_impact_summary": { "changes": { ... }, ... },
  "recommendations_summary": { "summary": { "critical": 0, ... }, ... }
}

POST /api/rollouts/:id/approve

Approve a rollout plan. Requires all evidence and critical recommendation acknowledgement.

Approval rules

Check Rule
State Must be review_ready
Evidence All 4 types attached
Validation Must be valid
Critical recommendations Must be explicitly acknowledged

Request

{
  "actor": "nalajmah",
  "reason": "Reviewed all evidence. Rolling out in dry-run first.",
  "acknowledged_recommendations": [
    "enable-dry-run-for-new-risky-policy"
  ]
}

Response

Returns plan with approved_by, approved_at, approval_reason, acknowledged_recommendations, and reviewed_evidence audit snapshot.


POST /api/rollouts/:id/reject

Reject a rollout plan. Transitions to rejected (terminal).

Request

{
  "actor": "nalajmah",
  "reason": "Critical risk not mitigated."
}

POST /api/rollouts/:id/promote

The only path that writes policy. Promotes the approved proposed config as the active repo policy.

Promotion rules

Check Rule
State Must be approved
Approval metadata approved_by, approved_at present
Evidence All 4 types attached
Validation Still valid
Proposed config Present

Execution sequence

  1. Capture previous config snapshot
  2. Write proposed config via setConfigOverrides
  3. If write fails → state remains approved (no transition)
  4. Transition to promoted

Request

{
  "actor": "nalajmah",
  "reason": "Promoting approved dry-run policy after successful review."
}

Response

Returns plan with promoted_by, promoted_at, promotion_reason, and previous_config snapshot.


POST /api/rollouts/:id/rollback

Restore the previous policy captured before promotion.

Rollback rules

Check Rule
State Must be promoted
Previous config Snapshot must exist
Actor Required
Reason Required

Execution sequence

  1. Capture current config as replaced evidence
  2. Write previous_config back as active policy
  3. If write fails → state remains promoted (no transition)
  4. Transition to rolled_back (terminal)

Rollback evidence

{
  "restored_previous_config": true,
  "replaced_config_captured": true,
  "previous_config_hash": "sha0:abc12345",
  "promoted_config_hash": "sha0:def67890",
  "replaced_config_hash": "sha0:ghi13579"
}

Request

{
  "actor": "nalajmah",
  "reason": "Observed unexpected live behavior after promotion."
}

POST /api/rollouts/:id/transition

Generic transition endpoint for non-specialized transitions (validated, review_ready, cancelled).

Blocks approved, rejected, promoted, rolled_back — those must go through dedicated endpoints.


Dashboard

The /rollouts dashboard page provides:

  • List view with filters and state badges
  • Detail view with lifecycle timeline, evidence cards, audit trail
  • State-driven actions with confirmation modal
  • Critical recommendation acknowledgement on approve
  • Collapsible redacted config snapshots