Cipi Api Laravel Package

Technical Evaluation

Architecture fit Release 1.35.0 extends the package's existing resource/job/ability architecture rather than introducing a parallel mechanism: a synchronous read endpoint (GET /api/apps/{name}/yml), an async job endpoint (POST /api/apps/{name}/yml/apply → app-yml-apply), and two idempotent toggle endpoints (/yml/auto/enable|disable). This mirrors the established pattern (plan-read, job-apply, ability gate) already used elsewhere in the API, so it slots into existing routing, job-dispatch, and OpenAPI-generation machinery. The new capability is essentially a thin, permissioned HTTP surface over cipi yml plan|apply|auto, which keeps business logic in the CLI and avoids duplicating deployment semantics in PHP. That is the right layering for a package whose job is to expose, not reimplement, server behavior.

Integration feasibility Straightforward for consumers that already speak the API: same auth model (bearer tokens + abilities), same job lifecycle abstraction, and OpenAPI is bumped to info.version 1.35.0 with four new paths under a cipi.yml tag plus three schemas (YmlPlanResponse, YmlAutoResponse, JobResultAppYmlApply). Generated clients can pick this up mechanically. Two real gating factors: (1) servers must run Cipi CLI ≥ 5.6.4 with the 5.6.4 migration applied, otherwise the new endpoints return 503 while all other routes behave as in 1.34.0 — so detection is cheap and blast radius is contained; (2) existing tokens do not receive the new yml-view / yml-manage abilities, so any automation must be re-issued tokens via cipi api token create. That is a safe-by-default choice but a guaranteed first-call failure for teams that assume version-bump parity.

Technical risk

• Privilege escalation via repository access (highest risk). With auto-apply enabled, anyone who can commit to the repo controls the app's server configuration. The release notes flag this explicitly and require client-side confirmation before enabling. Any UI or automation that enables auto-apply without an explicit, informed human action is a security defect.
• Sudoers surface expansion. /etc/sudoers.d/cipi-api now permits cipi yml plan *, cipi yml apply *, cipi yml auto *. The wildcard form broadens what a compromised API token can do at root; worth auditing whether argument injection through {name} is fully constrained.
• Partial-success semantics. The apply job can end partial with applied/failed/failures, and blocked/invalid/no-file end as failed while still carrying a result payload. Consumers that treat job failure as "no body" will mishandle these.
• Silent version coupling. 503 is the only signal of an under-versioned server; without a preflight check, retry logic may misclassify it as transient.
• MCP payload size. 76 tools still fit one tools/list page, but that is a large single response to feed an LLM context; monitor as it grows.

Key questions

1. Is the 503 distinguishable from other 503s (error code/header), and is it documented in OpenAPI responses?
2. Does {name} validation prevent traversal/injection into the sudoers-permitted CLI invocations?
3. Is in_sync a trustworthy gate for "nothing to do," or should clients always apply?
4. What is the retry-safety story for app-yml-apply — is apply idempotent enough to re-run after a timeout mid-job?
5. Does enabling auto-apply emit an audit event identifying the token/actor?
6. Is the 5.6.4 migration reversible, and what happens to auto-apply state on downgrade?

Integration Approach

Stack fit Fits a standard Laravel consumer stack with no new runtime dependencies: HTTP client + token, an async job poller (queue-aware), and optional OpenAPI codegen. Teams using the bundled MCP server get read-only (AppYmlShow), job (AppYmlApply), and toggle (AppYmlAuto) tools at MCP 1.5.0 with no bespoke glue. Nothing here requires new PHP extensions, packages, or a schema change on the client side.

Migration path

1. Upgrade the Cipi CLI on target servers (cipi self-update) and run the 5.6.4 migration. Confirm cipi yml plan <app> --json and cipi yml auto status --json execute locally — this is the definitive readiness check.
2. Upgrade the package to 1.35.0; verify OpenAPI info.version reads 1.35.0 and the cipi.yml tag is present.
3. Re-issue API tokens with yml-view (read-only consumers) and yml-manage (writers) via cipi api token create. Keep yml-manage tokens scoped to the smallest set of apps/pipelines possible.
4. Regenerate or hand-patch clients against the new schemas.
5. Enable the auto-apply toggle only after a deliberate change-management step; treat it as a repo-permission change, not an app setting.

Compatibility Additive at the API level — "every other route is as in 1.34.0," so 1.34.0 consumers are unaffected. Behavioral deltas worth noting in the changelog you publish internally: job results now backfill a missing app key from job parameters (consumers should not assume app is always CLI-derived), and the token-ability gap makes the new endpoints effectively invisible to pre-existing credentials. Rollback to 1.34.0 leaves the CLI features in place but removes the HTTP surface; no data migration is implied.

Sequencing Read-only first (GET /yml, yml-view token) to validate reachability, schema shape, and 503 handling in staging → manual apply in a non-production app with a known-clean cipi.yml to exercise applied and unchanged outcomes → deliberate failure injection to observe blocked, invalid, no-file, and partial payloads → only then consider auto/enable, gated behind an explicit confirmation UI and an audit trail. Do not enable auto-apply in the same change window as the upgrade; keep it a separate, reversible decision.

Operational Impact

Maintenance Low steady-state cost: the package delegates to the CLI, so drift risk lives in CLI/package version skew, not in duplicated logic. The maintenance burden is version discipline — a documented minimum (CLI ≥ 5.6.4) that must be asserted in runbooks and preflight checks, plus token rotation when abilities change. Expect ongoing attention to the sudoers whitelist as new cipi yml verbs appear.

Support New first-line questions are predictable: "403 on the new endpoints" (token lacks yml-view/yml-manage) and "503 on the new endpoints" (CLI below 5.6.4). Both should be in the KB with exact remediation commands. Escalation path for partial/blocked outcomes lands on whoever owns the app's cipi.yml, and for auto-apply incidents on repo access control — a different on-call group than the API team. Define that boundary before enabling auto-apply.

Scaling Negligible additional load: one synchronous read, one idempotent toggle pair, and one queued job per apply. The apply job shares the existing worker pool, so the practical constraint is queue concurrency during fleet-wide rollouts — batch applies rather than fanning out to all apps at once. Repeated yml plan polling is cheap but should be backed off rather than tight-looped. MCP tools/list at 76 tools remains a single page; if it crosses the pagination threshold, agent clients will need to handle multi-page discovery.

Failure modes

• 503 on new endpoints — CLI/migration prerequisite unmet; detect and surface as a configuration error, not a transient fault.
• 403 / missing ability — token predates 1.35.0; re-issue rather than widening an existing token.
• failed job with a populated result (blocked, invalid, no-file) — clients that discard failure bodies lose the actionable blockers/errors. Parse the result on both success and failure paths.
• partial — some changes landed, some did not; requires per-item failures reporting and a defined retry/rollback policy, since re-applying may be non-idempotent.
• Auto-apply drift — an unreviewed commit silently reconfigures a live app. Mitigations: confirmation gate at enable time, notification on every auto-apply, and periodic in_sync monitoring to catch divergence.
• Sudoers wildcard abuse — a leaked yml-manage token becomes a root-configuration primitive; scope tokens narrowly and rotate on suspicion.

Ramp-up Small, well-bounded learning curve. A developer familiar with the existing job/ability model can ship the read path in under a day; the apply path needs roughly a day more to handle outcome variants correctly. The genuinely new concept is the trust boundary introduced by auto-apply — that belongs in a short, mandatory briefing for anyone with repo write access to a Cipi-managed app, not in API documentation. Budget one sprint for upgrade + staging validation across the fleet, with auto-apply as a follow-on decision rather than part of the 1.35.0 rollout itself.