# Promote an immutable image

Source: https://docs.imprezahost.com/image-promotions.html

Use the portal, REST API or hosted MCP. Local MCP tools require MCP 0.36.0 or later.

Promote the image selected by one application to another existing application. Only the image changes: the destination keeps its environment variables, domain, ports, resource limits, startup configuration and volumes. Source credentials and variables are never copied.

## Before you start

Both applications must belong to your account and use image mode. The source must be running, select a registry reference ending in `@sha256:` followed by 64 lowercase hexadecimal characters, and have a successful recorded deploy of that exact reference. Mutable tags and local Docker image IDs are not promotion artifacts. The destination must be running or failed and have one image service named `app`.

If either app is linked to a [project environment](project-environments.html), both must have the same project, component name and role in different environments. Changing the association invalidates the saved review.

The source record is historical evidence, not a fresh application health check. Check the source application's behavior before choosing it. The target host must be able to pull the image; registry credentials are not transferred. A multi-platform digest can select different architecture-specific images on different hosts.

Portal access requires permission to manage services. REST prepare/apply require `deploy` scope; reading the saved review requires `read`. Hosted MCP currently requires account credentials without resource restrictions. No automatic agent update or fleet rollout is performed.

## Review and apply

In **My Apps**, switch to Advanced mode, open **Promote an image** on the destination card, select the source app and choose **Review promotion**. Check the exact image, destination server, domain, limits and variable names. Choose **Confirm and promote** only after reviewing the possible traffic interruption.

With MCP:

1. Call `impreza_prepare_image_promotion` with `deployment_id` for the destination and `source_deployment_id` for the source.
2. Review the returned summary. It contains variable names, never their values.
3. After customer confirmation, call `impreza_apply_image_promotion` with the returned `promotion_id`, `review_digest` and `confirm: true`.
4. Read `impreza_get_image_promotion` with `promotion_id` to retrieve the saved review or accepted command receipt.

Equivalent REST requests, using the usual authenticated API headers:

```http
POST /v1/platform/deployments/custom/dpl_target/prepare-promotion
Content-Type: application/json

{"source_deployment_id":"dpl_source"}
```

```http
GET /v1/platform/deployments/custom/promotions/prom_REPLACE_WITH_RETURNED_ID
```

```http
POST /v1/platform/deployments/custom/promotions/prom_REPLACE_WITH_RETURNED_ID/apply
Content-Type: application/json

{"review_digest":"REPLACE_WITH_RETURNED_DIGEST","confirm":true}
```

Preparation creates a private review, not a deployment job or capacity reservation. Reviews expire after 15 minutes; at most 20 pending reviews are retained per account. Apply accepts only the reviewed digest and confirmation. It rejects source or destination changes after review.

## Verify the result

A `202` response confirms queue acceptance, not successful deployment. Follow the returned `command_id` in **Deployment history**, inspect the destination's runtime health and test the application. Repeating the same promotion ID and digest returns its existing receipt, including after a lost response, without creating another command.

The destination's selected image becomes the promoted image when the command is accepted. If pulling or replacement fails, its running version may still be the earlier release. Read the recorded result before retrying; selected configuration and current runtime are separate facts.

## Limits and troubleshooting

- `409 CONFLICT`: stale/expired review, changed configuration, mutable source tag, missing successful source record, or a busy application. Review the current state and prepare again when appropriate.
- `404 NOT_FOUND`: unavailable application, promotion or current server ownership.
- `422 UNSUPPORTED`: the destination is not a supported single image service.
- `429 QUOTA_EXCEEDED`: wait for a pending review to expire.
- `503 PROMOTION_UNAVAILABLE`: storage or verification failed. Read the saved promotion before retrying the same confirmation; do not assume it was accepted.

Promotion can interrupt traffic. It does not implement blue-green switching, change database schemas, revert data writes, export locally built images or transfer registry credentials. Existing deployment preparation/recovery rules apply. This increment does not implement environment groups, provider previews or a managed artifact registry.

## Related reference

- [Deployment safety and rollback](/deployment-safety.html)
- [Runtime health and diagnostics](/runtime-health.html)
- [REST API reference](/api.html)