> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pivotal.app/llms.txt.
> For full documentation content, see https://docs.pivotal.app/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pivotal.app/_mcp/server.

# Move through phases

Phase moves change the `phase` field on the onboarding and write a `PhaseTransition` entry to the [audit log](/product/onboardings/audit-log). Every move runs the same pipeline: validate, write the transition, fire notifications, fire webhooks. There's no "soft" move that skips any of it.

## Who can move an onboarding

| Role        | Advance         | Send back       | Skip ahead |
| ----------- | --------------- | --------------- | ---------- |
| Admin       | Yes             | Yes             | Yes        |
| CSM (owner) | Yes             | Yes             | No         |
| Member      | Yes if assigned | Yes if assigned | No         |
| Read-only   | No              | No              | No         |

The CSM is whoever holds the `csm` field on the onboarding. A member counts as "assigned" if they own any open task in the current phase.

## Advance one phase

1. Open the onboarding from the Workbench or **Customers > \[name] > Onboardings**.
2. Click **Advance phase** in the header. The next phase in the workspace sequence appears in the confirmation dialog.
3. Add an optional note. The note lands on the `PhaseTransition` entry, not on the task list.
4. Confirm. The onboarding moves, the previous phase locks for editing on customer-facing views, and the new phase opens.

If the previous phase has open tasks, you see a prompt: leave them as carryover (they stay open, attributed to the prior phase) or mark them complete on the spot. Pi treats carryover tasks as overdue once you advance.

## Send back to a previous phase

Click the phase pill in the header and pick an earlier phase. You'll be required to enter a reason. The reason is non-optional because the field surfaces in the customer's portal under "what happened" and in the [audit log](/product/onboardings/audit-log).

Common reasons:

* **Scope changed**: customer expanded the integration mid-UAT.
* **Failed UAT**: a test case didn't pass, work resumes in Integration.
* **Blocked on customer**: Pause the onboarding instead; see [onboarding states](/product/onboardings/onboarding-states).

## Skip a phase

Admins only. Use **Phase > Jump to...** and pick any later phase. Tasks in the skipped phase stay open and Pi flags them as orphaned. Skipping is the right move when a phase doesn't apply (e.g. a free trial with no Integration work), and the wrong move when work in that phase is incomplete.

## What fires on every move

* A `PhaseTransition` record with `from_phase`, `to_phase`, `actor`, `reason`, `timestamp`.
* An email to the customer's primary contact if the new phase is customer-facing.
* A Slack notification in the customer's channel if [Slack is connected](/product/integrations/connect-slack).
* An `onboarding.phase_changed` [webhook](/webhooks/overview) with the full transition payload.

## Gotchas

* Email notifications respect the customer's portal settings. If the customer has muted phase updates, no email goes out, and the audit log records `notification_skipped: muted`.
* A move with zero open tasks in the new phase looks empty on the kanban. Apply a [phase template](/product/onboardings/phase-templates) at move time to populate it.
* You can't undo a move. To reverse one, send back with a reason.

## Related

* [The phase model](/product/onboardings/the-phase-model)
* [Audit log](/product/onboardings/audit-log)
* [Onboarding states](/product/onboardings/onboarding-states)

Email **[help@pivotal.app](mailto:help@pivotal.app)** with a screenshot of where you got stuck and the customer or onboarding id from the URL.