Cloudbase Declarative Deploy

CloudBase Declarative Deploy

Deploy a whole CloudBase project from one cloudbaserc config as desired state, using the deployPlan (dry-run) and deployApply (apply) MCP tools. The orchestrator applies resources in a fixed dependency order:

database → functions → app → hosting → gateway

Sibling skills (local only)

Sibling CloudBase skills ship beside this skill. Use local relative paths such as ../cloudbase-cli/SKILL.md.

Cloud-hosted MCP mode does not guarantee access to a local workspace filesystem or stable relative paths. If a referenced sibling file is not available in cloud mode, use this skill's embedded guidance as source of truth and ask the user for any missing constraints — do not HTTP-fetch remote skill markdown.

Cross-cutting protocols (required before applying any deploy):

• Change Safety Protocol: ../cloudbase-platform/references/protocols/change-safety-protocol.md
• Deployment Gate: ../cloudbase-platform/references/protocols/deployment-gate.md

When to use this skill

• The project has a cloudbaserc.json / .yaml / .yml / .js describing multiple resources, and the user wants to deploy them together as one config.
• The user asks for 声明式部署 / 配置式部署 / "deploy from cloudbaserc" / "deploy the whole project".
• The user wants to preview what a deploy will change before applying (dry-run plan).
• Multi-environment deploy: production/staging via mode + envOverrides.

Do NOT use for

• Deploying a single cloud function or one static site via tcb CLI → ../cloudbase-cli/SKILL.md.
• In-app SDK integration (web/miniprogram/node) → the matching SDK skill.
• Console UI operations.

Cloud mode

deployPlan / deployApply in this skill are the local-form declarative executor. In cloud-hosted MCP mode these tools are intentionally not registered (filtered at tool registration), because that runtime has no local cwd / filesystem-bound execution path.

If you are in cloud mode and do not see deployPlan / deployApply in the tool list, this is expected behavior.

Use the cloud upload-channel path instead:

1. queryApps(action=getUploadUrl) to get uploadUrl, uploadHeaders, unixTimestamp
2. Upload source/build zip to uploadUrl with returned headers
   • If cloud build requires private/offline dependencies, package node_modules explicitly
   • For public dependencies, uploading package.json + lockfile is typically enough
3. manageApps(action=deployApp, cosTimestamp=<unixTimestamp>, installCmd?, buildCmd?, deployCmd?)
   • installCmd / buildCmd / deployCmd are pipeline declarations executed in cloud container
   • Agent passes data + declarations; it does not execute local shell commands

Planned cloud declarative path (incremental roadmap): upload cloudbaserc as a data artifact, then run server-side plan/apply orchestration. deployApply remains the local-form executor of the same declarative spec.

For parameter details, see references/plan-and-apply.md (Cloud-hosted upload pipeline path).

Core principles

1. Plan before apply — always. Run deployPlan first (dry-run, zero side effects). Read the per-resource action classification and show it to the user before calling deployApply.

2. Apply requires explicit confirm. deployApply will refuse unless confirm=true is passed. This is the destructive-write guard.

3. Deployment Gate. Before any apply, complete cloudbase-platform/references/protocols/deployment-gate.md and present the mandatory declaration.

4. Conservative on existing resources by default. yes defaults to false → existing resources are skipped, not overwritten. Only pass yes=true when the user explicitly wants to overwrite/update existing resources.

5. database failure always aborts. Even with continueOnError=true, a database-stage failure stops the whole deploy, because later resources depend on it.

6. Resolve envId explicitly. Never rely on implicit defaults silently — know which environment is targeted (see the priority table below) and confirm it with the user before applying.

Plan action classification

deployPlan returns a list of resource entries. Each status means:

If any entry is conflict, stop and resolve it before applying.

envId resolution priority

explicit envId param  >  cloudbaserc `envId`  >  logged-in / bound environment

If none can be resolved, the tool errors out. Prefer confirming the resolved envId with the user before applying to production.

Two-step workflow (local mode)

1. Ensure a cloudbaserc config exists under the project root (cwd).
2. Call deployPlan (optionally with mode, envId, only, skip). Read the plan.
3. Present the plan + Deployment Gate declaration to the user; get confirmation.
4. Call deployApply with confirm=true (plus yes / concurrency / continueOnError as needed). Reuse the same mode / envId / only / skip as the plan.
5. Report the applied result back to the user.

For cloud-hosted MCP mode, do not ask for local cwd/filesystem reads; use the Cloud mode upload-channel flow above.

Build & pipeline execution

Use this mental model: build → plan → apply. The build executor depends on resource type.

Build command resolution follows declaration priority:

explicit config > framework mapping defaults > package.json auto-detection

buildCommand / installCommand / deployCmd are declarative intent in config. Execution ownership depends on path:

• local-form paths: specific steps may run in local shell executor
• cloud-hosted paths: commands are executed by cloud pipeline container (staticCmd), or replaced by prebuilt artifact upload

So the answer to "can cloud mode run local CLI commands" is: execution authority is moved from local shell to cloud pipeline; agent transmits declarations and artifacts.

Routing

Minimum self-check

• Ran deployPlan and read the action classification before deployApply?
• Resolved and confirmed the target envId?
• Completed the Deployment Gate declaration before applying?
• Passed confirm=true only after user confirmation?
• Left yes=false unless overwrite of existing resources was explicitly requested?
• Handled any conflict entries before applying?

Reference index

All packaged reference files (required for skill lint reachability):

• config-schema.md
• plan-and-apply.md
• multi-env.md