Api Laravel Package

Getting Started

1. Update the package, then verify config/cipi.php contains the new token abilities yml-view and yml-manage.
2. Create or rotate an API token with the abilities you need:
   • yml-view for read-only plan/inspection.
   • yml-manage for apply and auto-apply changes. Existing tokens will not receive these abilities automatically.
3. Confirm the target server runs Cipi CLI ≥ 5.6.4 (cipi self-update, migration 5.6.4), otherwise the new /yml endpoints return 503.
4. Look first at:
   • The OpenAPI cipi.yml tag and schemas YmlPlanResponse, YmlAutoResponse, JobResultAppYmlApply.
   • The new MCP tools AppYmlShow, AppYmlApply, AppYmlAuto.
   • CipiCliService::ALLOWED_COMMANDS, which now whitelists yml plan, yml apply, yml auto.
5. First day-to-day use case: inspect an app’s live cipi.yml before changing anything.
   • Call GET /api/apps/{name}/yml or use AppYmlShow.
   • Read file, auto, valid, errors, warnings, changes, blockers, notes, and in_sync.
   • Only then decide whether to apply changes or enable auto-apply.

Implementation Patterns

• Preview before apply. Treat GET /api/apps/{name}/yml as the standard preflight for any configuration change. Surface valid, errors, warnings, changes, and blockers in your admin UI or deploy script before offering an apply action.
• Apply through the async job. Use POST /api/apps/{name}/yml/apply and poll the app-yml-apply job result. Model the outcome explicitly:
  • applied, unchanged: successful terminal states.
  • partial, blocked, invalid, no-file: job ends as failed, but still carries applied, failed, failures, blockers, and errors. Do not discard that payload.
• Use deployment hooks deliberately. After a successful deploy, call the plan endpoint to show drift or blockers. If the team has opted in, enable auto-apply instead so configuration is applied after successful Git-webhook deploys.
• Gate auto-apply behind explicit confirmation. POST /api/apps/{name}/yml/auto/enable and .../disable are synchronous and idempotent, returning {app, auto, sudoers, file}. Enabling auto-apply means anyone who can commit to the repository can change the app’s server configuration. Confirm intent and audit who has repo access.
• Use least-privilege tokens. Give dashboards and read-only tooling yml-view; reserve yml-manage for deploy automation and trusted operators.
• Integrate through MCP where appropriate. Use AppYmlShow for read-only inspection, AppYmlApply for the apply job, and AppYmlAuto for enable/disable state changes. If your MCP client caches tools, refresh it for server version 1.5.0 and the 76-tool listing.
• Regenerate API clients. OpenAPI info.version is now 1.35.0, with four new paths under cipi.yml and new app-yml-apply job type. Regenerate typed clients before wiring the new endpoints.
• Keep CLI shell-outs on the whitelist. If your Laravel code shells out through CipiCliService, use the newly allowed yml plan, yml apply, and yml auto commands rather than raw cipi calls.

Gotchas and Tips

• 503 is a server-version signal, not an app error. New /yml endpoints require Cipi CLI ≥ 5.6.4 and the matching sudoers entry. Feature-check the server version or handle 503 with a clear “upgrade required” message.
• Existing tokens cannot use the new endpoints. Create a token with yml-view / yml-manage. This is a common source of immediate 403 or missing-action failures after upgrade.
• Auto-apply is a security boundary. With auto-apply enabled, repository commit access effectively controls server configuration. Confirm before enabling, review the returned sudoers value, and disable it when the deployment model does not require it.
• Apply is not immediate. Handle app-yml-apply as a job. blocked, invalid, partial, and no-file end as failed; always read the embedded result instead of relying only on the job status.
• Resolve blockers before retrying. blockers are explicit reasons apply will refuse. Do not retry blindly. Distinguish errors (invalid config) from warnings (potentially acceptable but worth surfacing).
• file: null means the live release has no cipi.yml. Expect no-file when applying. Decide whether that is a valid state for the app before building UI around it.
• Sudoers whitelist matters. The API sudoers file must allow cipi yml plan *, cipi yml apply *, and cipi yml auto *. The sudoers field in auto responses is a useful diagnostic; check it when commands work over SSH but fail through the API.
• Job result app handling changed. If the parsed CLI result has an app key that the CLI text could not fill, it is now taken from the job parameters. Consume the job’s app field rather than parsing CLI text yourself.
• MCP tool-list caching can hide new tools. The MCP server is now 1.5.0 with 76 tools in one tools/list page. If AppYmlShow, AppYmlApply, or AppYmlAuto are missing, refresh the client cache or restart the MCP client.