> For the complete documentation index, see [llms.txt](https://umber.gitbook.io/umber/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://umber.gitbook.io/umber/concepts/deployment-states.md).
# Deployment States
## 1. What a state is
A **state** describes whether a deployable thing — an asset version or a virtual collection — is currently being served from a given environment. There are three of them:
| State | Meaning |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Not deployed** | Never deployed to this environment. No row exists for it yet — the dashboard shows no badge, just a **Deploy Here** action. |
| **Live** | Deployed to this environment and servable. |
| **Offline** | Deployed to this environment but not currently servable. Taking something offline stops serving it without deleting it — it can be set Live again at any time. |
You move between these three with the same three actions everywhere they appear: **Deploy Here** (not deployed → Live), **Take Offline** (Live → Offline), **Set Live** (Offline → Live).
{% hint style="info" %}
You may briefly see something's state as "processing" right after triggering Live or Offline — this resolves to Live or Offline by the time the action completes, usually within the same request. It isn't a state you ever need to act on.
{% endhint %}
## 2. States apply to both versions and collections
This same three-state model — not deployed, Live, Offline — governs both [Virtual Assets](/umber/concepts/virtual-assets.md) (per version) and [Virtual Collections](/umber/concepts/virtual-collections.md). Deploying, taking offline, and re-deploying use the same **Deploy Here** / **Take Offline** / **Set Live** actions for both. Collections stop there — there's no Default pointer for them (see below), so the **Set Default** / **Revert** actions described later on this page apply to asset versions only.
Where they differ is the subject of the rest of this page: a collection has only one servable thing per environment, so its state is the whole story. An asset can have many versions active in the same environment at once, which is what sections 3 and 4 below are about.
## 3. A version's state is scoped to one environment — for its one platform
**Platform is a fixed tag on a version, set when it's created and never changed afterward.** A version belongs to exactly one target platform (`generic`, `web`, `ios`, or `android`) — it never spans more than one, and it can't be retagged to a different one later. An asset can hold several versions across different platforms (say, `WEB1`/`WEB2` on web and `AND1` on android), but any one version is only ever "the web one" or "the android one," not both.
What actually varies per version is the **environment**: the same version can be Live in `dev`, not deployed at all in `staging`, and Offline in `prod` — each environment tracks that version's state independently. The combination of a version's (fixed) platform, its asset, and one environment is sometimes called a **channel** — it's the thing a state and a default belong to.
This is why [Managing Deployments](/umber/guides/managing-deployments.md) is laid out the way it is: the platform tabs choose *which versions* you're looking at (only ones tagged for that platform), the environment picker chooses *which channel's* state and default you're seeing for them — platform isn't a per-deploy choice the way environment is.
Collections carry the same fixed-platform, per-environment scoping for their own Live/Offline state, but without the multi-version layer described next.
## 4. Default: an asset-version concept only
**Default** is a separate fact, and it only applies to asset versions.
Here's the problem it solves: an environment can have more than one Live version of the same asset at once — say `WEB1` and `WEB2`, both deployed, both technically servable. But the asset's one public URL for that environment can only ever return a single file. **Default is whichever Live version that URL currently returns.**
Before promoting `WEB1`, the URL resolves to `WEB2` — `WEB1` is Live too, but nothing requesting the URL sees it:
```mermaid
flowchart LR
URL(["🔗 dev · public URL"]):::url
WEB1["WEB1
Live"]:::live
WEB2["WEB2
Live · Default"]:::default
URL ==>|default| WEB2
URL -.->|not served| WEB1
classDef url fill:#eef2ff,stroke:#4f46e5,stroke-width:2px,color:#312e81,font-weight:bold
classDef live fill:#f8fafc,stroke:#94a3b8,stroke-width:1.5px,color:#475569
classDef default fill:#ecfdf5,stroke:#059669,stroke-width:3px,color:#065f46,font-weight:bold
```
Clicking **Set Default** on `WEB1` moves the pointer — it doesn't touch either version's own state:
```mermaid
flowchart LR
URL(["🔗 dev · public URL"]):::url
WEB1["WEB1
Live · Default"]:::default
WEB2["WEB2
Live"]:::live
URL ==>|default| WEB1
URL -.->|not served| WEB2
classDef url fill:#eef2ff,stroke:#4f46e5,stroke-width:2px,color:#312e81,font-weight:bold
classDef live fill:#f8fafc,stroke:#94a3b8,stroke-width:1.5px,color:#475569
classDef default fill:#ecfdf5,stroke:#059669,stroke-width:3px,color:#065f46,font-weight:bold
```
Both versions are still Live in both diagrams — only the thick green arrow moved. **Revert** does the same move in reverse, back to `WEB2`.
{% hint style="info" %}
**This is the whole point of the pointer model.** The `dev` public URL in these diagrams never changes — not one character of it, in either diagram. Your app, your `![]()
` tag, your API response was already pointing at that URL before you ever created `WEB1`. Promoting it to default is an administrative click, not a deploy: no code change, no file rename, no redeploying whatever consumes the URL. The new version is live to every caller of that URL the instant the pointer moves.
{% endhint %}
Default isn't a fourth state — a version can only become default while it's already Live, and stays Live the whole time it holds that position. In the dashboard this shows as a border, pointer marker, and **Default** label on the row, not a badge (see [Managing Deployments](/umber/guides/managing-deployments.md)).
A few consequences follow from default being a pointer rather than a state:
* **Only one version per channel can be default at a time.**
* **You can't take the current default offline directly.** Revert it first, then take the demoted version offline if you want to.
* **Revert only goes back one step.** It points a channel's default back to whichever version it targeted immediately before the current promotion. If that previous version is no longer Live, the revert is rejected rather than falling back further.
**Virtual Collections have no default concept at all.** A collection has a single Live pointer per environment (and platform) — there's no "which of several Live collections" question to resolve, so there's nothing to promote or revert.
## Where this shows up
* [Managing Deployments](/umber/guides/managing-deployments.md) is the primary place to read and change all of this, per environment, for asset versions.
* [Deployment History](/umber/guides/managing-deployments.md#deployment-history) is a running log of every state and default change.
* A channel's public URL (see [Environments](/umber/concepts/environments.md)) always resolves to whatever is currently default (for a version) or Live (for a collection) — never a specific version, unless you request a version-specific URL directly.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://umber.gitbook.io/umber/concepts/deployment-states.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.