Promote copies definitions from one environment to another: tables, access rules, flows, routes, agents, templates and the rest. It never copies data, secrets, keys or users, so promoting can’t leak anything or overwrite real records.

​
Promote step by step

1

Open the environment you built in

For example development.
2

Choose Promote from the environment menu

Pick the target (for example staging). The two must be different.
3

Choose what to include

Tick the kinds to copy, or leave them all.
4

Review the changes

Studio shows what would be added or changed, and the table changes needed in the target. Nothing happens yet: this is a dry run.
5

Confirm

The definitions are copied and the additions are applied.

​
What happens to your tables

Promoting is careful with your data:
  • Only additions are made automatically: new tables, new columns, new indexes.
  • Renames, type changes and removals are left for you to review. Studio lists them but does not apply them, so a promote can never drop a column that holds real data.

​
Things to remember

  • Rules your tables use must go with them. If a table uses a named rule, include rules in the promote, or the table can’t resolve it in the target.
  • Secrets are not copied. Add each secret the new environment’s flows and connections need under Secrets.
  • Knowledge bases arrive empty. The base is copied, not its documents. Add them in the target.
  • Connections need their keys. A connection copied across has no key until you add one in the target.
  • AI models and providers are not part of promote. Connect providers and add models in each environment, using the same model names so agents keep working.

​
A safe routine

  1. Take a backup of the target.
  2. Promote to staging, test.
  3. Promote to production.
  4. Watch Activity.

​
What can block a promote

Some additions can’t be made to a table that already has rows. The usual one is a new required column with no default: existing rows would have no value. The review lists these under blocked, and confirming is refused (409) until you fix it, for example by giving the column a default or making it optional first, then requiring it after you’ve filled it in. See Migrations and history.

​
Choosing what to include

Leave include empty to promote everything, or choose kinds: Promote only kinds that belong together. A table that uses a named rule needs that rule; a subscription needs its flow.

​
From code

The source is the environment in the address; to must be another environment of the same project. A dry run answers with definitions (what would be added or changed), tables (per table: the changes that would be applied and those that need review) and blocked. A real promote answers with what was copied and how many table changes were applied.

​
Promote or deploy from code?

Promote copies what’s in an environment. Infrastructure as code deploys what’s in your repository. Teams that review changes in pull requests usually deploy from code to every environment; teams that build in Studio usually promote.