> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tinfoil.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Staging mode

> Stage container updates for manual promotion.

## What is staging mode?

Staging mode lets you test a ready update through Tinfoil's staging ingress
before manually promoting it. It is intended for validating a tag before it
replaces the currently serving instance.

## When to use staging mode

* **Validating a new release tag** before switching production traffic
* **Pinning a long-lived test instance** to a specific tag
* **Manually controlling promotion** of ready updates instead of relying on the automatic blue-green flip

## How it works

Staging containers use the same production certificate flow as normal
containers. The difference is in update promotion: production containers
auto-promote a ready update to live traffic, while staging containers hold
it on the staging ingress until you manually promote or cancel it.

When an update for a staging container becomes ready, the existing instance
continues serving production traffic. The ready update candidate remains
available through the Tinfoil staging ingress until you promote or cancel it.

Staging mode is independent from [debug mode](/containers/debug-mode) — a
container can be in staging, in debug, in both, or in neither.

## Deploying a staging container

1. In the **All Containers** tab, click **New Container**
2. Configure the container as normal
3. Tick the **Staging** checkbox above the launch button
4. Click **Deploy in Staging**

You can also tick **Staging** in the **Update Instance** dialog or the
**Start Container** dialog to deploy a new tag straight into staging without
touching production.

## Updating a staging container

To pick up a new tag on a staging container, click **Update**, select the tag, and click **Deploy in Staging**.

If a staging update candidate becomes ready while the container itself is
already in staging, click **Promote Update** to switch traffic to the staged
instance, or **Cancel Update** to discard it.

## Promoting to production

A staging container shows a **Deploy to Prod** button in its action sidebar.
Click it to relaunch the container with the same tag and configuration in
production mode. The new instance goes through the normal blue-green
relaunch flow and, once ready, is marked as the GitHub `latest` release.

This is the recommended path. If you instead want to deploy a new tag directly
to production, open the **Update** dialog, leave the **Staging** checkbox
unchecked, and click **Update** — the same end-state is reached.

The GitHub `latest` release is bumped only when the post-deploy mode is
neither staging nor debug.

## Setting a repository default

Set staging as the default for new instances and deployment-wide updates:

```bash theme={"dark"}
tinfoil deployment settings myorg/my-api-config --default-staging true
```

Repository updates inherit this setting unless you pass `--staging true` or `--staging false`:

```bash theme={"dark"}
tinfoil deployment update myorg/my-api-config --tag v1.0.1
tinfoil deployment update myorg/my-api-config --tag v1.0.1 --staging false
```

## Using the CLI

The [Tinfoil CLI](/containers/cli) supports the same staging flow:

```bash theme={"dark"}
# Deploy directly into staging
tinfoil container create my-api \
  --repo myorg/my-api-config \
  --tag v1.0.0 \
  --staging

# Push a new tag into staging without touching production
tinfoil container relaunch my-api --tag v1.0.1 --staging true

# Promote a "ready" staged candidate, or discard it
tinfoil container update status my-api
tinfoil container update accept my-api    # promote
tinfoil container update cancel my-api    # discard

# Promote to production by relaunching with staging=false
tinfoil container relaunch my-api --staging false
```