Evolving Previews & Overrides

While most pull requests only modify a single microservice, complex cross-cutting features often require testing simultaneous changes across multiple services (for example, updating both the gateway and an internal service-b service).

Envy supports selecting up to 3 approved component overrides in a single composition.

---

These examples use the demo application and images installed by the local quickstart. Replace the example composition ID with the ID returned at creation, and wait for readiness after each create or update.

Defining Multiple Overrides via CLI

Use repeated --override flags with envy composition create:

envy composition create \
  --project demo \
  --baseline staging \
  --name feat-checkout-v2 \
  --override gateway=envy/gateway:v2 \
  --override service-b=envy/service-b:v2 \
  --ttl 6h

---

Request Routing with Multiple Overrides

When both gateway and service-b are overridden:

Two overrides, one request path

The preview starts at gateway v2, reuses service-a v1, and selects service-b v2. Applications forward composition context at each HTTP hop. The database and cache remain shared.

Preview overrideShared baseline

Scroll sideways to follow wider branches, or read the connections below.

Read the connections

• Preview URL → gateway · v2: preview request.
• gateway · v2 → service-a · v1: forward baggage.
• service-a · v1 → service-b · v2: composition=cmp-84f1a.
• service-b · v2 → Database & cache: read / write.

1. Ingress Route: The preview hostname routes directly to the overridden gateway-v2 container instead of the baseline gateway.
2. Intermediate Hops: gateway-v2 calls service-a, which remains shared from the deployed reference baseline. The local demo uses staging as that baseline’s catalog ID.
3. Downstream Mesh Route: When service-a calls service-b, the selected mesh route inspects the baggage: composition=cmp-84f1a header and redirects the call to service-b-v2.

---

Updating Multi-Service Compositions

You can update individual images independently during rolling updates by providing the complete desired override set:

envy composition update cmp-84f1a \
  --expected-generation 1 \
  --override gateway=envy/gateway:v2 \
  --override service-b=envy/service-b:v3

Add or remove services without changing the URL

Updates provide the complete desired selection, with zero to three overrides. To remove gateway while keeping the changed service-b:

envy composition get cmp-84f1a
envy composition update cmp-84f1a --expected-generation 2 \
  --override service-b=envy/service-b:v3
envy composition wait cmp-84f1a --timeout 60s

Use the current generation returned by get, not a stale value copied from an example. Add services by including them alongside every override you want to retain. Omitted components return to the baseline. The URL and expiry stay fixed; updates do not renew TTL. A stale generation returns a conflict, so inspect the new state before deciding whether to retry.

Use only the baseline

Create a preview URL without deploying any override workloads:

envy composition create --project demo --baseline staging \
  --name baseline-review --inherit-all --ttl 2h

Or return an existing preview to full inheritance:

envy composition update COMPOSITION_ID --expected-generation GENERATION --inherit-all

These previews still have a lifecycle, routing resources, and a TTL. Shared baseline services and data remain live, so a baseline-only preview is not a snapshot. REST and MCP express this selection as "overrides": {}.

Select published builds

For an onboarded source repository, resolve the desired revision and select a published build from the result:

envy source resolve --project shop --repository backend --component pricing --ref main
envy composition create --project shop --baseline staging --name pricing-review \
  --build pricing=BUILD_ID

Replace BUILD_ID with the returned ID for the intended commit. If no build exists, publish it through CI first. Envy resolves that build to its registered artifact and source provenance. --build and --override can be mixed for distinct components, up to three total. Direct images carry no source provenance.

Wait, verify, and clean up

Every create or update needs a readiness wait followed by your application tests. Rollouts are not atomic across components. A failed new image can leave the old override serving; Envy does not silently route that override back to the baseline. Changing the project, baseline, expiry, or message-isolation choice requires a new composition. Destroy disposable previews after verification.

GitHub App-owned previews follow their repository policy and exact-head builds; generic composition updates cannot change them. Their policy requires one to three overrides. Independent UI, CLI, and agent previews retain the zero-to-three behavior described here.

For capturing events and attaching consumers later, see Google Pub/Sub isolation.