Preview, Publish, and Roll Back

Personalization follows the same branch, promotion, and immutable-release workflow as other ACI content. The additional requirement is a decision matrix: review the base experience and every targeted outcome before activation.

What each environment proves

Environment	What it proves
Local compile	Resource shapes, references, overlay merges, contracts, and compiled variants
Local framework server	Base rendering, component behavior, and responsive layout
Branch preview	Branch content with its linked code, plus explicit variant selection; collection is disabled
Staged release preview	The exact immutable release intended for activation
Active site	Production delivery, consent, identity, collection, and natural audience or experiment selection

A successful local render does not prove request-time selection or collection. Complete those checks on the appropriate ACI preview and active-site surfaces.

1. Run local validation

npm run content:compile
npm run typecheck
npm test
npm run build

Fix every compilation error before pushing. ACI validates the complete resolved variant, so a small overlay can reveal a missing required prop or reference in the final experience.

2. Dry-run the branch update

Use the credentials and API URL supplied for your site:

npm exec -- aci branch create personalization-enterprise \
  --source-ref main

npm exec -- aci content push \
  --branch personalization-enterprise \
  --dry-run

Review every path in the plan, then push:

npm exec -- aci content push \
  --branch personalization-enterprise

Site configuration at /config/site.json is code-owned and is not overwritten by content push. If the change adds an overlay dimension or collection setting, include it in the linked code build and confirm the remote site configuration before publishing.

3. Review the branch preview

For an audience experience, compare at least:

<branch-preview>/
<branch-preview>/?aci_audience=enterprise

For an experiment, select both dimensions:

<branch-preview>/?aci_experiment=home-hero&aci_experimentArm=control
<branch-preview>/?aci_experiment=home-hero&aci_experimentArm=outcome-led

Explicit aci_* dimensions are authoring-preview controls. They select an existing compiled variant without changing production targeting. Branch preview disables visitor collection, which keeps author review traffic out of measurement. Verify the collector separately on an edge-backed active environment. For each outcome, review:

page and shared-fragment content;
metadata, canonical URL, and structured data;
navigation and calls to action;
mobile and desktop layout;
base fallback when no selector is present; and
any locale and audience combinations in scope.

4. Land the approved branch

Read the current branch and target state, then land with the observed heads. The expected-head check prevents the land from silently overwriting newer work on either side:

npm exec -- aci branch land personalization-enterprise \
  --target-ref main \
  --expected-head "$BRANCH_HEAD" \
  --expected-target-head "$MAIN_HEAD"

Landing moves the approved change to main. It does not put the change on the live site. If the branch is behind main, rebase it, resolve any path conflicts, rerun the checks, and review the updated preview before landing.

5. Promote approved paths to `live`

Use aci drift to see approved changes that are not yet live:

npm exec -- aci drift

Promote the audience, segment, and overlay as one reviewed set:

npm exec -- aci promote \
  --path /segments/high-intent/_index.json \
  --path /audiences/high-intent/_index.json \
  --path /overlays/audience/high-intent/pages/home/_index.json \
  --note "Publish high-intent homepage experience" \
  --yes

aci promote always validates and prints a dry-run plan first. Without --yes, it stops after that plan. Review co-change warnings before continuing so related paths do not get separated accidentally.

6. Stage the release

npm exec -- aci release publish

Keep these values from the output:

releaseId: <staged-release>
previewUrl: <staged-preview>
currentReleaseId: <currently-active-release>
currentActiveGeneration: <observed-generation>

Open the staged preview and repeat the complete decision matrix. Do not use release publish --activate when you need a separate review gate.

7. Activate with the observed state

Activation requires the active release and generation observed when the new release was staged:

npm exec -- aci release activate <staged-release> \
  --expected-release <currently-active-release> \
  --expected-generation <observed-generation>

For a site’s first activation, pass an empty expected release:

npm exec -- aci release activate <staged-release> \
  --expected-release "" \
  --expected-generation 0

If the active state changed during review, activation stops. Inspect the newer release, then restage or retry with newly observed values rather than overwriting someone else’s activation.

8. Verify live behavior

Immediately after activation:

open the base route without preview selectors;
exercise each natural request rule in scope;
verify consented behavior-based targeting with a test identity;
confirm the collector and goal event on an active edge-backed page; and
confirm unrelated routes still use the expected active release.

9. Roll back if verification fails

Rollback selects a previously staged immutable release without rebuilding it:

npm exec -- aci release rollback <previous-release> \
  --expected-release <current-release> \
  --expected-generation <current-generation>

Use the active release and generation observed by your ACI workflow. These values protect rollback from replacing a newer activation. After rollback, verify the live base page and the targeting paths that triggered recovery. The replaced release remains available for investigation and correction.

Release rollback restores the whole previous release. To reverse selected content paths while keeping other approved work, promote an older revision of those paths to live, then publish a new release.

Review checklist

Next: Content Versioning →

⌘I

​What each environment proves

​1. Run local validation

​2. Dry-run the branch update

​3. Review the branch preview

​4. Land the approved branch

​5. Promote approved paths to live

​6. Stage the release

​7. Activate with the observed state

​8. Verify live behavior

​9. Roll back if verification fails

​Review checklist

What each environment proves

1. Run local validation

2. Dry-run the branch update

3. Review the branch preview

4. Land the approved branch

5. Promote approved paths to `live`

6. Stage the release

7. Activate with the observed state

8. Verify live behavior

9. Roll back if verification fails

Review checklist