Environments
The Environments page of a project: development, staging, UAT and production with their addresses, branch and flags; the scheduled health check; freezing changes; and what a client guest sees of it.
By the end of this page you will have registered where a project runs, know every field an environment carries and what reads each one downstream, know how the scheduled health check works and how a change freeze is declared and lifted, and know which environments a client guest is shown.
An environment is one named place a project's software runs: a developer's machine, the shared development server, QA, staging, the UAT the client signs off on, pre-production and production. Each has a kind, the component it runs or the whole project, the addresses people and pipelines open, the branch deployed there, two flags that will govern deployments and the health the last check found. Deployments will land on environments, releases will promote through the kinds in order and incidents will name the one that failed, so the record every later phase reads starts here.
Before you begin
| You want to | You need |
|---|---|
| Open the Environments page | environment:view-any on the project. Every staff role has it; a client guest has it through their project membership. |
| Add an environment | environment:create, through your role on the project or your team role, or to own the team. |
| Edit one, or check its health | environment:update. |
| Freeze or lift a freeze | environment:freeze. Project managers, release managers and admins have it by default. |
| Delete one | environment:delete. |
| Name the component it runs | The component to exist already; add it on the Components page first. |
The page lives under a project: open the project from the selector or the registry and choose Environments in the sidebar's Selected Project group. The entry is badged with the number of environments you may see.
Read the environments
The table lists one environment per row, in the project's order: local first, then development, QA, staging, UAT, pre-production, production and custom, and within a kind in the order they were added.
| Column | What it shows |
|---|---|
| Environment | The name, with the component it runs (or Whole project) and its address beneath it. Press the name to open the detail flyout. |
| Kind | Local, development, QA, staging, UAT, pre-production, production or custom, as a coloured badge. |
| Health | Healthy, degraded, down or not checked, with how long ago the last check ran. |
| Branch | The branch deployed there. Staff only. |
| Flags | Frozen while a change freeze is in force, Protected when a deployment there needs a promotion approval, Auto deploy when the pipeline deploys there without a hand. |
| Updated | How long ago the record last changed. |
| Row menu | View Environment, Edit Environment, Check Health Now, Freeze Changes or Lift Freeze, Activity, Delete Environment. |
Sort by environment, kind, health or updated by pressing a column heading; press it again to flip the direction. Above the table, narrow the list with the search box (words in the name or an address), the kind list, the component list and the health list. The filters travel in the page address, so a filtered list can be shared; Clear Filters on the empty state drops them all.
Add an environment
- Press New Environment.
- Type the Name and pick the Kind. The name is unique within the project and the component: Staging for a shared staging, API Staging when the API has its own.
- Pick the Component the environment runs, or leave Whole project when every component shares it.
- Add the Addresses you know: what people open, the API, the back office, and the address the scheduled health check should call.
- Under Deployment, name the Branch deployed there and the Current Version running now, say where it is hosted and in which region, and set Auto deploy and Protected.
- Put access notes, quirks and who to call in the Notes. Never a secret: the record is read by everyone who sees the project.
- Press Create Environment.
The environment appears in the table at once and environment.created goes out to every endpoint
subscribed to it. The usual set is development, staging, UAT and production; add the rest as the
project needs them.
A name and a kind are enough
The addresses, the branch and the flags can follow once the environment exists. A health check starts the moment its address is saved and stops the moment it is cleared.
Open an environment
Press an environment's name, or View Environment in its row menu, to open the detail flyout: the name with the component beneath it, the kind, health and flag badges, then Addresses (address, API address, admin address), Deployment (branch, current version, hosting, region), Health (when it was last checked, the streak of failed checks when there is one, or No health check address), the Change Freeze and its end, the Notes and the created and updated stamps. From the flyout, Edit, Check Now, Freeze or Lift Freeze, Activity and Delete are one press away.
A link such as /projects/<project>/environments?show=<id> opens the page with that environment's
flyout already open; notifications and Heimdall's buttons use it.
Edit an environment
- Press Edit Environment in the row menu, or Edit in the flyout.
- Change what you need. The same rules as adding apply: the name stays unique within the project and component, every address is a full URL, the component is one of the project's.
- Press Save Changes.
Every change travels as environment.updated with its old and new values. An edit that changes
nothing announces nothing.
The health check
An environment with a Health Check Address is checked on a schedule. Every few minutes the application queues a check for every environment whose last check is older than the interval, and each check opens the address and reads the answer:
| The address answers | Health |
|---|---|
| A success status (2xx) | Healthy |
| A server error (5xx), or nothing within the timeout | Down |
| Anything else: a redirect, a 404, a 401 | Degraded |
The answer is written with the time it was read, and the Health column and badge update. A
change from one health to another is announced as environment.health_changed with the previous
and the new health; the same answer twice in a row announces nothing. A streak of checks that found
the environment down is counted and shown in the flyout, and reset by the first answer that is not
down; the maintenance module will read the streak to open an incident when production stays down.
Check Health Now in the row menu (or Check Now in the flyout) queues one check at once instead of waiting for the schedule. It needs a health check address; without one the request is refused with a message saying so. A monitoring system of your own can write the health it observed through the REST API instead, and the same event fires when it changes.
Freeze changes
A change freeze says that nothing is to be deployed into an environment until a moment you name: the client's month-end, a trade show, a long weekend with nobody on call.
- Press Freeze Changes in the row menu, or Freeze in the flyout.
- Set Freeze until, in your own timezone. The moment must be in the future.
- Press Freeze.
The row shows a Frozen badge and the flyout shows when the freeze ends; environment.frozen
goes out with that moment. While it is in force, deployments into the environment are refused and
the pipelines are told so. The freeze lifts itself when the moment passes; Lift Freeze ends it
early and announces environment.unfrozen.
Delete
Delete Environment removes the environment with its activity history after a confirmation; there is no undo. Deployments and releases that will name environments are not here yet; once they are, an environment with history will be archived rather than deleted.
What a guest sees
A client guest invited to the project sees the Environments page with the UAT and Production environments only, because those are the two they open: the name, the component, the address, the kind, the health and the flags. The branch, the admin address, the hosting note, the region, the health check address, the failure streak and the notes are not shown, and the guest's own API token leaves those fields out of the payload rather than nulling them. An environment of another kind answers 404 to a guest wherever its address is typed.
All the fields
What happens next
- Every add, edit, freeze, lift, delete and recorded health is written to the environment's activity history; the scheduled check is recorded as the application acting, with no person named.
- The
environment.created,environment.updated,environment.deleted,environment.frozen,environment.unfrozenandenvironment.health_changedevents go out to every endpoint subscribed to them. - A component that environments run cannot be deleted until they are moved or removed.
- Deployments, releases and incidents will name environments as those modules land, and the flags, the freeze and the health are what they will read.
Heimdall on this page
Heimdall reads the environments through the same tools the MCP server offers and carries the open project as its context.
Registering environments, freezing them and recording their health is a person's or a pipeline's work: Heimdall and an agent over MCP read the record and never write to it.
From the API and MCP
Environments API
List, get, create, change, freeze, unfreeze, record health for and delete environments over REST.
list_environments and get_environment
The two MCP tools that read a project's environments as the token sees them.
Permissions
| Action | Permission |
|---|---|
| See the environments | environment:view-any; a guest sees UAT and production only |
| Open an environment | environment:view |
| Add an environment | environment:create, or owning the team |
| Edit, or check health now | environment:update, through a project role or a team role |
| Freeze, or lift a freeze | environment:freeze |
| Delete an environment | environment:delete |
Frequently asked
Related
- Components — the applications environments run
- The project overview — the project the environments belong to
- Status reference — every kind and health
environment.*webhook events
How is this guide?
Last updated on
Components
The Components page of a project: the web app, the API, the mobile apps and the services it is made of, each with a slug, a kind, a tech stack and an owner; adding, editing, archiving, restoring and deleting them.
Stakeholders
The Stakeholders tab of a project's People pages: the client's sponsor, product owner and approvers, Zuse's own leads and third parties, each with a side, a role, a weight and the approvals that name them; adding, editing and removing them, and what a guest sees.