Environments and Deploys
Create App environments, follow a branch, build and deploy releases, set env vars, and inspect data.
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
- On your computer, run the tests and the local preview. Try an action a role allows and one it denies.
- Deploy to a development or staging environment to test real connections, workflows, table changes, and what members may do.
- Build the tested commit for production, review its changes, and deploy.
To go back, deploy an earlier release.
Create an environment
- On the App page, open the Environment picker and select New environment.
- Enter a Name: lower-case letters, digits, and dashes, such as
staging. - Choose the Branch and the Data store. The store is fixed once the environment exists. See Data Stores.
- 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 see | Meaning and next step |
|---|---|
| Up to date | Nothing to do. |
| Deploy change | New commits. Select it to build and deploy the latest. |
| Building commit | Select it to open the build. |
| Build of commit failed | Select it to read the build, fix the cause, then Retry. |
| Deploy version | Built, and waiting for you or blocked. Hover for the reason, then select it to review and deploy. |
| No commits yet | Commit 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.
| Column | Values |
|---|---|
| Trigger | manual, auto-deploy, or check (runs the App's tests and never deploys). |
| State | queued, running, succeeded, failed, or cancelled. |
| Deploy | pending, deployed, blocked, failed, or skipped (automatic deploys were turned off, or a newer build exists). |
Build errors:
| Error | Fix |
|---|---|
UNSUPPORTED_DEPENDENCY | Import only @botdojo/app, react, and react-dom. |
LOCK_OUT_OF_DATE | The lock file lacks new IDs. Run botdojo-app build and commit botdojo.app.lock.json. |
DEFINITION_INVALID | botdojo.app.ts does not compile. The message names the problem. |
BUILD_FAILED | Read 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.
- Review Schema (table and field changes) and Roles (added +, changed ~, removed -).
- Fill in Env vars this release needs and select Save and check again.
- 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:
| Blocker | What to do |
|---|---|
| A field changes type | Add a new field and move the data in a function. |
| A reference field points at another table | Add a new field. |
| A field becomes required without a default | Give it a default. |
| A retired table or field comes back | Use a new name. |
| A required env var is missing or invalid | Enter 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
- Share the environment and give groups their roles.
- Write an App in code.