> ## 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.

# Holding an update for review

> Keep the current version serving while you try the new one at its review URL, then promote it.

## What holding does

On a new project, an update switches traffic to the new version as soon as it is running. Holding an update for review keeps the current enclave serving production while the new version boots and gets its own **review URL**. Nothing changes for your users until you **promote** the held version. Updates inherit the project's hold default unless explicitly overridden.

Use it to check a release against production configuration before it takes traffic.

## How it works

Holding applies to blue/green updates: running CPU-only and single-GPU instances without persistent volumes. It is also available for instances selected by a [project update](/containers/updates#updating-a-project). Initial creates and deploys of stopped or failed instances have no current version to keep serving and cannot be held. Multi-GPU updates and [updates with persistent volumes](/containers/updates#updates-with-persistent-volumes) stop the running enclave before deploying the new version, so they cannot be held either. The CLI's `--hold` flag is available on update commands, not on create or deploy.

When the held version is running, the instance card shows **Held · ready to promote** with its review URL. Try it there, then choose **Promote** to switch production traffic to it, or **Cancel update** to discard it while the current version keeps serving.

If project-update preflight finds an eligible instance whose target release requires replacement, a requested hold returns `HOLD_UNAVAILABLE` before any instance is updated.

## Setting a project default

Hold every update of a project for review by default:

```bash theme={"dark"}
tinfoil project settings myorg/my-api-config --hold-by-default=true
```

New projects have `hold_by_default=false`. Individual updates, edited-config updates, and batch project updates inherit the saved setting. An explicit `--hold=true` or `--hold=false` overrides it for one operation, without changing the project default:

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

## Using the CLI

```bash theme={"dark"}
# Hold the new version for review instead of switching traffic
tinfoil container update my-api --tag v1.0.1 --hold=true

# Inspect the candidate and its verified request command
tinfoil container get my-api
tinfoil container connect my-api --review -p 3301
```

The update command returns when the candidate is ready for review, not after promotion.
It and `container get` print the available review URL and a verified `tinfoil http get`
command pinned to the candidate's repository and tag. Use that command for a one-off
request, or keep the review proxy above running and use another terminal:

```bash theme={"dark"}
curl http://127.0.0.1:3301/
```

This local request goes through the verified proxy. A direct request to the review URL
with ordinary `curl` does not verify attestation. `--review` refuses an unavailable
candidate instead of silently connecting to production. Keep any port in the returned
review URL; do not substitute the production domain or tag. Debug candidates still fail
attestation and must not receive sensitive data.

After checking the candidate, choose one action:

```bash theme={"dark"}
# Promote the held version, or discard it
tinfoil container get my-api        # shows the update tag and stage
tinfoil container promote my-api    # switch production traffic
tinfoil container cancel my-api     # discard
```

Promotion can mark the tag as GitHub's repository-wide latest release if that option was
enabled for the update. Use `--mark-latest=false` when initiating the update if you do not
want that effect. Cancel discards the candidate without switching production traffic.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.