Browse Apps
Apps · Deploy and Share

Environments and Deploys

Create App environments, follow a branch, build and deploy releases, set env vars, and inspect data.

5 min read

An environment is one running copy of an App, with its own Store, env vars, branch, releases, roles, and App connection.

A build turns a commit into a numbered release for one environment, and a deploy makes the environment run it. A release deploys only to the environment it was built for. To run the same commit in another environment, build it there.

Test and roll out changes

  1. On your computer, run the tests and the local preview. Try an action a role allows and one it denies.
  2. Deploy to a development or staging environment to test real connections, workflows, table changes, and what members may do.
  3. Build the tested commit for production, review its changes, and deploy.

To go back, deploy an earlier release.

Create an environment

  1. On the App page, open the Environment picker and select New environment.
  2. Enter a Name: lower-case letters, digits, and dashes, such as staging.
  3. Choose the Branch and the Data store. The store is fixed once the environment exists. See Data Stores.
  4. To make it the production environment, select This is the production environment, or Make this the production environment instead. Then select Create.

The new environment has no release, data, or env vars. Build and deploy to run the App there. If the dialog shows Link repo, link the App's repo under Settings → Source first.

The production environment

Choose it under Settings → Production environment. In production:

  • Seed data is never accepted.
  • Deploy change asks you to confirm.
  • Automatic deploys build each commit, then wait for you to review and deploy it.
  • Agents deploy only through separate tools that ask first.

Branch and deploys

Every environment follows one branch. To change it, select the branch name beside the Environment picker, pick the Branch, choose what happens to new commits, and select Save.

  • Build and deploy automatically: each new commit is built and deployed once the build passes and its plan has no blockers. Saving also deploys the latest commit right away.
  • Wait for me: Deploy change appears beside the branch when it has new commits.

Automatic deploys:

  • Wait for your review when a release changes what a role may do or the connections the App declares.
  • Run as the administrator who turned them on, and stop if that person is no longer an administrator.
  • Are not offered for an external Git source. See Deploy the same App to multiple accounts.

Build and deploy new commits

Beside the branch name, the App page shows where the environment stands and the next step.

You seeMeaning and next step
Up to dateNothing to do.
Deploy changeNew commits. Select it to build and deploy the latest.
Building commitSelect it to open the build.
Build of commit failedSelect it to read the build, fix the cause, then Retry.
Deploy versionBuilt, and waiting for you or blocked. Hover for the reason, then select it to review and deploy.
No commits yetCommit to the branch.

Deploy change first asks for required env vars the environment lacks.

Builds

The Builds tab lists every build for the environment. A build takes an exact commit and builds it in an isolated builder with no network access. Select a build to read its output.

ColumnValues
Triggermanual, auto-deploy, or check (runs the App's tests and never deploys).
Statequeued, running, succeeded, failed, or cancelled.
Deploypending, deployed, blocked, failed, or skipped (automatic deploys were turned off, or a newer build exists).

Build errors:

ErrorFix
UNSUPPORTED_DEPENDENCYImport only @botdojo/app, react, and react-dom.
LOCK_OUT_OF_DATEThe lock file lacks new IDs. Run botdojo-app build and commit botdojo.app.lock.json.
DEFINITION_INVALIDbotdojo.app.ts does not compile. The message names the problem.
BUILD_FAILEDRead the builder output.

Releases

The Releases tab lists the releases built for this environment and marks the active one. Version numbers are unique across the App. Select Deploy on another release to review and deploy it. An older release must fit the tables as they are now, and deploying it does not restore data.

Review and deploy a release

Deploy version beside the branch and Deploy on a release open the same dialog.

  1. Review Schema (table and field changes) and Roles (added +, changed ~, removed -).
  2. Fill in Env vars this release needs and select Save and check again.
  3. Resolve any blockers, then select Deploy version. The environment switches in one step, and its data stays.

New tables, new fields, and renames declared in code deploy without help. These changes are blocked:

BlockerWhat to do
A field changes typeAdd a new field and move the data in a function.
A reference field points at another tableAdd a new field.
A field becomes required without a defaultGive it a default.
A retired table or field comes backUse a new name.
A required env var is missing or invalidEnter it in the dialog.

Deployments

The Deployments tab is the environment's history. Each successful deploy increases its Generation.

Env vars

The Env Vars tab lists the environment's values. Secret values are never shown. The App's code declares each env var and its type. Set values in the deploy dialog, or with botdojo-app env set or deploy --vars-file.

Data

The Data tab shows one table of the Store at a time, up to 100 rows, read with your App roles. App tables also appear on the project's Datasets page under the App environment, but not in dataset tools.

To load seed.json into an empty, non-production environment, deploy with botdojo-app deploy --seed.

Preview the App

Select Preview App to open the running release inside BotDojo as a project administrator with every role. It is unavailable until a release is deployed.

Next steps