---
description: Deployment workflow -- check-first, dev vs prod, version bumping, common errors
paths:
  - operations/**
---
<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
<!-- Regenerate: pnpm scaffold:sync -->


# Deployment

## Always Check Before Deploy

```bash
pnpm -C operations run check        # Validate resource definitions
pnpm -C operations run check-types  # TypeScript type-check
pnpm -C operations run deploy       # Deploy to dev (only after both pass)
```

`check` catches duplicate resource IDs, OM descriptor/code mismatches, invalid step chains, broken relationships, and schema serialization issues. Same validation runs during deploy -- if `check` passes, deploy validation will pass.

## Dev vs Prod

| Command                              | Target            | When                    |
| ------------------------------------ | ----------------- | ----------------------- |
| `pnpm -C operations run deploy`      | Local dev API     | Development and testing |
| `pnpm -C operations run deploy:prod` | `api.elevasis.io` | Production release      |

Always test in dev first, verify with `elevasis-sdk exec`, then deploy to prod.

## Version Bumping

Deploy accepts `--major`, `--minor`, `--patch` flags to bump the deployment version. The bumped version is written back to `src/index.ts`. Bump on contract changes (input/output schema modifications).

## What Gets Deployed

1. **Bundle:** esbuild compiles `src/index.ts` + all dependencies into a single self-contained CJS file. No `node_modules` needed at runtime.
2. **Metadata:** Resource definitions, OM Resources descriptor bindings, Zod schemas (converted to JSON Schema), relationships, triggers.

## Environment

- `ELEVASIS_PLATFORM_KEY` in `.env` is required for CLI auth
- `.env` is never included in the bundle -- it stays local
- Integration credentials live in Command Center, not `.env`

## Common Errors

| Error                                    | Fix                                                                                                 |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `401: Invalid API key`                   | Check `ELEVASIS_PLATFORM_KEY` in `.env`                                                             |
| `Duplicate resource ID`                  | Fix the duplicated OM Resource descriptor ID, then derive runtime `resourceId` from that descriptor |
| `Missing OM Resource descriptor`         | Add the descriptor to `core/config/organization-model.ts` under the id-keyed `resources` map        |
| `Step references non-existent next step` | Fix the `next:` field in the step chain                                                             |
| `Schema serialization failed`            | Simplify the Zod schema (warning, still deploys)                                                    |
| `No default export found`                | `src/index.ts` must `export default` a `DeploymentSpec`                                             |
| `Documentation file exceeds 100KB`       | Split the `.md` file                                                                                |

## Deployment Replaces Previous

Only one deployment can be `active` at a time. Deploying again automatically marks the previous deployment as `stopped`. Resources become executable immediately after deploy succeeds.
