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

# Roll out Bily to production

> Release browser, API, and MCP changes in stages, with clear proof and a ready rollback path.

Release a small, reviewed contract. Prove it with real flows. Expand only when the result matches your event plan.

## Make the release ready

Before you begin, confirm:

* one owner approves the event names and business meaning;
* one browser installation path owns loading;
* the exact production tracking URL comes from the intended Bily store;
* page-view ownership is documented for direct loads and SPA routes;
* customer fields have consent and privacy approval;
* API and MCP credentials are created for the intended workload and scope;
* every write has a verification read and rollback decision.

## Move through four release gates

### Gate 1: Prove the code locally

* The project builds and type-checks.
* Bily imports remain safe during server rendering.
* The application sends no success event on a failed operation.
* Event payloads contain only reviewed fields.

### Gate 2: Prove real flows in staging

* One Bily script loads with the exact URL.
* One initial page view appears.
* Later SPA routes produce one explicit page view each.
* Representative product, checkout, order, and custom events match the event plan.
* Login, logout, consent-denied, and storage-restricted paths behave as expected.
* Read-only API and MCP discovery calls use the intended organization and store.

### Gate 3: Start with limited production exposure

* Release to the smallest practical traffic or operator group.
* Run a short, named verification window.
* Compare event counts to the expected product actions, not to an unrelated metric.
* Inspect at least one real payload for every new or changed event.
* Exercise one safe read for each new API or MCP workload.

### Gate 4: Expand to full production

* Expand only after the limited window passes.
* Remove temporary SDK diagnostics.
* Record the release time, owner, event changes, credential changes, and verification evidence.
* Keep the rollback path available until the next stable review window.

## Evolve events without breaking the contract

Make additive changes when possible:

* add a new property before removing an old one;
* keep property types stable;
* add a new event when the business meaning changes;
* avoid renaming events and properties in place without a migration window.

If two systems can emit the same logical outcome during a migration, give both one stable `event_id` and test the result. An event ID does not guarantee exactly-once ingestion.

## Introduce API workloads one step at a time

1. Start with `GET /context` and select an exact nested store URL.
2. Verify one read-only store endpoint.
3. Preserve `x-request-id` in logs.
4. Add bounded retries only for safe reads.
5. Before a write, read the current state and record the intended change.
6. After a write, read the state again before reporting success.

When the first result is uncertain, do not automatically repeat a create, clone, update, toggle, delete, sync, or mutation request.

## Keep MCP actions visible and verifiable

1. Keep approval mode set to prompt.
2. Use `search` immediately before an unfamiliar operation.
3. Review the complete `execute` function, including every helper call.
4. Begin with an identity, store, or analytics read.
5. Introduce one approved action at a time.
6. Verify every action with the catalog's recommended read.

Planning metadata is advisory. One `execute` call can contain several helper calls, so the client review must cover the complete function.

## Know when to roll back

Roll back or disable the new path if:

* the script fails to become ready;
* the initial page view duplicates;
* a high-value event is missing or fires before success;
* a property changes type or contains unapproved customer data;
* an API job crosses the intended organization or store boundary;
* an MCP action differs from the reviewed function or verification result.

If verification disagrees with the requested state, stop additional writes.

## Confirm the result after release

In the first stable review window:

* compare expected product outcomes with observed Bily events;
* inspect samples across signed-out, signed-in, and consent states;
* review API errors by status and request ID;
* review MCP actions and their verification reads;
* remove temporary credentials and test-only event paths;
* update the event catalog with the final production contract.

<CardGroup cols={2}>
  <Card title="Validation and debugging" icon="list-check" href="/guides/validation-debugging" />

  <Card title="Migration guide" icon="arrow-right-arrow-left" href="/migrations/2-0" />
</CardGroup>