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

# Preview, Publish, and Roll Back

> Validate every personalized outcome, promote approved paths, activate a release, and recover safely.

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 |

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

## 1. Run local validation

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
npm exec -- aci content push \
  --branch personalization-enterprise
```

<Note>
  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.
</Note>

## 3. Review the branch preview

For an audience experience, compare at least:

```text theme={null}
<branch-preview>/
<branch-preview>/?aci_audience=enterprise
```

For an experiment, select both dimensions:

```text theme={null}
<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:

```bash theme={null}
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:

```bash theme={null}
npm exec -- aci drift
```

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

```bash theme={null}
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

```bash theme={null}
npm exec -- aci release publish
```

Keep these values from the output:

```text theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

1. open the base route without preview selectors;
2. exercise each natural request rule in scope;
3. verify consented behavior-based targeting with a test identity;
4. confirm the collector and goal event on an active edge-backed page; and
5. 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:

```bash theme={null}
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.

<Warning>
  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.
</Warning>

## Review checklist

* [ ] Content compile, typecheck, tests, and build passed
* [ ] Base experience passed
* [ ] Every audience and experiment arm passed
* [ ] Missing-signal and no-consent fallbacks passed
* [ ] Locale combinations and shared fragments passed
* [ ] Branch preview contained no unexpected paths
* [ ] Promoted paths and co-change warnings were reviewed
* [ ] Staged release passed before activation
* [ ] Active release and generation were recorded
* [ ] Live targeting and collection passed after activation
* [ ] Previous release ID is available for rollback

***

*Next: [Content Versioning →](/aci/architecture/content-versioning)*