Cipi Api Laravel Package

Product Decisions This Supports

• Roadmap: GitOps and self-service server configuration. The new cipi.yml endpoints turn app server configuration into an API-managed workflow: inspect the live release file, validate it, preview changes/blockers, apply asynchronously, and toggle auto-apply after successful deploys. This supports a roadmap item for “configuration as code” without building a bespoke orchestration layer.
• Build vs. buy: avoid custom deploy-time YAML tooling. Instead of building internal tooling around cipi yml plan / cipi yml apply, product and platform teams can expose these operations through the existing API, job system, OpenAPI schema, and MCP tools. The package already handles validation, blockers, partial/blocked outcomes, and async job results.
• Feature prioritization: safe configuration changes over raw automation. The release emphasizes valid, errors, warnings, changes, blockers, and in_sync, which supports features that prioritize guardrails and explainability before applying server changes. This is more valuable than a simple “apply config” button.
• Use cases: CI/CD, drift detection, platform ops, and agent-assisted operations. Product can enable workflows such as: pre-deploy validation, post-deploy auto-apply, drift review from the live cipi.yml, controlled rollout via yml-manage tokens, and MCP-based read/apply/auto tools for internal agents or operator assistants.
• Security and permissions product decisions. New token abilities (yml-view, yml-manage) allow read-only vs. write access separation. The explicit warning that auto-apply lets repository committers control server configuration is a product-level security decision that should be surfaced in UX and documentation, not buried in API behavior.

When to Consider This Package

• Adopt when the platform runs Cipi CLI ≥ 5.6.4 and needs programmatic access to cipi.yml planning, applying, and auto-apply status. On older servers, the new endpoints return 503, so upgrade/migration planning is a prerequisite.
• Consider it when you need API-first or agent-first server configuration management — for example, a control plane, internal developer platform, CI/CD integration, or MCP-based assistant that must inspect and apply app-level Cipi configuration.
• Adopt when token-scoped permissions matter. Teams that need separate read-only visibility (yml-view) from apply/auto-apply rights (yml-manage) get a clean authorization boundary, but must create new tokens because existing tokens do not receive the new abilities.
• Look elsewhere or defer if you are not on the required Cipi CLI version, do not use cipi.yml-based configuration, cannot accept the security model where repo commit access can imply server configuration control via auto-apply, or need synchronous apply semantics. The apply endpoint is an async job, and several outcomes intentionally end as failed while still returning results.
• Treat as additive, not breaking. This release adds endpoints, abilities, MCP tools, and OpenAPI paths; existing routes otherwise match 1.34.0. The main adoption gates are CLI version, token reissuance, and operational review of auto-apply.

How to Pitch It (Stakeholders)

For executives: This release moves app server configuration into a governed API workflow. Teams can validate and preview cipi.yml changes, see blockers before applying, apply changes as tracked async jobs, and optionally auto-apply after successful deploys. The business value is safer configuration change management, less custom tooling, and a foundation for GitOps-style operations — with explicit permission controls and audit-friendly job results.

For engineering: The package now exposes GET /api/apps/{name}/yml, async POST /api/apps/{name}/yml/apply, and idempotent auto-apply enable/disable endpoints, plus yml-view / yml-manage token abilities, MCP tools, and OpenAPI schemas. It wraps cipi yml plan, cipi yml apply, and cipi yml auto, requires Cipi CLI ≥ 5.6.4, and returns 503 on older servers. Existing tokens must be recreated to gain the new abilities. Auto-apply should be treated as a privileged capability because repository commit access can become server configuration control.