cloudbase-declarative-deploy v2.33.2A

Immutable. This exact content is served forever at /api/v1/blob/5205e0ea944b11d0.

---
name: cloudbase-declarative-deploy
description: CloudBase declarative deployment from a cloudbaserc config (声明式部署, 配置式部署, cloudbaserc 部署) through the deployApply / deployPlan MCP tools. Use when deploying database, functions, app, hosting, or gateway resources described in cloudbaserc.json/yaml as a single desired-state config, when a user wants a dry-run plan before applying, or when handling multi-environment deploys via mode / envOverrides. Covers plan-then-apply flow (deployPlan dry-run → deployApply confirm=true), envId resolution priority, only/skip filtering, concurrency, and continueOnError. Prefer deployPlan before deployApply; do not confuse with per-resource tcb CLI deploy or single-function deploy.
version: 2.33.2
alwaysApply: false
---

# 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:

| status | meaning |
|--------|---------|
| `create` | new resource, will be created |
| `update` | exists, will be overwritten/updated |
| `skip` | no change needed |
| `conflict` | conflict detected — deploy will abort, must resolve first |
| `deploy` | direct overwrite upload |

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.

| resource | typical build executor | deployment path |
|----------|------------------------|-----------------|
| `hosting` | local shell (when `buildCommand` is set) | upload build output |
| `app` (`framework=static`) | local prebuilt artifact | package upload + deploy record |
| `app` (non-static frameworks) | cloud pipeline | source zip upload + cloud build + deploy |
| `functions` | local zip / cloud build / image pipeline | depends on `buildStrategy` (`zip`/`cloud`/`local`/`image`) |

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

| User task | Read |
|-----------|------|
| cloudbaserc resource fields & desired-state config shape | `references/config-schema.md` |
| deployPlan → deployApply two-step flow, parameters, safety | `references/plan-and-apply.md` |
| Multi-env (mode / envOverrides), envId priority, env vars | `references/multi-env.md` |

## 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](references/config-schema.md)
- [plan-and-apply.md](references/plan-and-apply.md)
- [multi-env.md](references/multi-env.md)