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 (or to install the missing skill). Do not HTTP-fetch remote skill or protocol markdown into the agent context.

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