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

# Publishing

> Publish a flow to create a servable version, then attach that version to a placement so the SDK serves it.

Editing a flow only changes its **draft**. The SDK never serves a draft. To make a flow reachable you do two separate things: **publish** it (which creates an immutable, servable version) and **attach** that version to a **placement** (which is what the SDK actually resolves). Getting these two steps confused is the single most common place builders get stuck, so this page keeps them clearly apart.

## The publish chain

```mermaid theme={null}
flowchart LR
  A[Edit draft] --> B[Publish]
  B --> C[New immutable version vN]
  C --> D[Attach to a placement]
  D --> E[SDK resolves the placement and serves vN]
```

A draft is the flow you are editing. Publishing freezes the current draft into a numbered version (`v1`, `v2`, ...) that can never change. A placement points at exactly one version through its `default_flow_version_id`. The SDK serves whatever version the placement points at.

## Save, publish, and attach

<Steps>
  <Step title="Let the draft save (or save it yourself)">
    The editor autosaves your draft to the server about 2 seconds after you stop editing, and keeps a local backup in your browser. You can also click **Save Draft** (file icon) in the top bar to save immediately. Either way, the draft is not served to any user. Only published versions are.
  </Step>

  <Step title="Publish">
    Click **Publish** (rocket icon) in the top bar. The editor saves the current draft first, then creates a new published version. A confirmation appears: "Flow published successfully. \{flow name} version vN is now live and immutable." The version is frozen at that point; later edits go back into the draft and do not change vN.
  </Step>

  <Step title="Attach to a placement">
    The success modal offers three choices:

    * **Attach to placement** (primary). Opens the attach modal described below.
    * **View placements**. Takes you to the placements list to wire it up later.
    * **Do nothing for now**. Closes the modal. The version exists but no placement serves it yet.

    Until you attach the new version to a placement, nothing changes for your users.
  </Step>

  <Step title="Choose how the placement uses the version">
    In the **Attach to placement** modal, pick a placement from the list, then choose a behavior:

    * **Replace current flow**. Immediately route all traffic at that placement to this version. This sets the placement's `default_flow_version_id` to the version you just published. If the placement already had a flow, the modal warns that live users will start seeing the new version right away.
    * **Add as experiment variant**. A/B test this version against the placement's current flow. (Marked "coming soon" in the current build; use the experiments flow to set this up. See [Experiments](/dashboard/experiments).)
    * **Schedule activation**. Activate the version on a future date. This option is disabled (coming soon).

    Confirm with **Confirm & attach**. If you have no placements yet, create one first; see [Placements](/dashboard/placements).
  </Step>
</Steps>

## Rolling out an update

A published version is immutable, so you never "edit a live flow." You publish a new version and point the placement at it.

<Steps>
  <Step title="Edit the draft">
    Make your changes in the editor. They accumulate in the draft.
  </Step>

  <Step title="Publish a new version">
    Click **Publish** again. This creates the next version (`v2`, `v3`, ...). The previous version is untouched and still attached wherever it was.
  </Step>

  <Step title="Point the placement at the new version">
    Attach the new version to the placement (Replace current flow), or update the placement's default version from the dashboard. The placement does not move to the new version on its own; see the warning below.
  </Step>
</Steps>

To roll the update out to a subset of users first, attach it as an experiment variant instead of replacing the default. See [Experiments](/dashboard/experiments).

## Notes and warnings

<Warning>
  **Publishing never repoints a placement by itself.** A placement pins one specific `flow_version_id`. Publishing `v2` does not move a placement off `v1`. You must explicitly attach `v2` (or update the placement's default version) for users to see it.
</Warning>

<Note>
  The SDK caches resolved flows on device, so even after you repoint a placement, updates reach users subject to the cache lifetime. A returning user may see the previous version until their cached copy refreshes. See [Caching](/ios-sdk/caching).
</Note>

## Common mistakes

* **Publishing but never attaching.** A published version that is not attached to any placement is invisible to the SDK. The SDK keeps serving the previously attached version, or nothing if the placement was never wired up.
* **Editing the draft and expecting an instant rollout.** Draft edits are never served. Nothing reaches users until you publish and the placement points at that new version.
* **Forgetting to bump the placement.** After publishing a new version, the placement still points at the old one until you repoint it.
* **Assuming a repoint is instant for everyone.** On-device caching means returning users may keep seeing the old version until their cache refreshes.

## Troubleshooting

| Symptom                                                     | Likely cause                                         | Fix                                                                                             |
| ----------------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Users still see the old flow after publishing               | The placement was never repointed to the new version | Attach the new version (Replace current flow) or update the placement's default version.        |
| "No placements found" in the attach modal                   | This app has no placements yet                       | Create a placement first, then publish and attach. See [Placements](/dashboard/placements).     |
| Users see nothing at the placement                          | The placement has no flow version attached           | Attach a published version to the placement.                                                    |
| New version published but a few users still see the old one | On-device cache has not refreshed yet                | Expected. Updates propagate subject to the SDK cache lifetime. See [Caching](/ios-sdk/caching). |

## Related pages

* [Placements](/dashboard/placements)
* [Managing flows](/dashboard/flows)
* [Experiments](/dashboard/experiments)
* [Preview and live mirror](/editor/preview-and-live-mirror)
* [Caching](/ios-sdk/caching)