Approval flows let you stage new resources (models and syncs) and changes to existing resources in draft mode until an approver reviews them.
Getting started
To enable approval flows:
- Navigate to Settings in the right sidebar.
- Open the Workspace tab.
- Enable Require approvals.
- Select Save.
After you enable approval flows, any role with the Draft models & syncs permission can save changes as drafts or submit them for approval — not just the built-in Workspace draft editor role.
Whether a user must get approval depends on their role:
- Users with draft-only roles must submit changes for approval before publishing.
- Users with publishing permissions can submit changes for approval or use Publish now to publish directly.
- Users with the
Approve models & syncspermission can review, approve, decline, or withdraw approval requests.
Require approval for a user
To require a user's model and sync changes to go through approval, assign them a role that enforces drafts.
Use the Workspace draft editor role
- Go to Settings > Members.
- Find the user.
- Change their role to Workspace draft editor.
Users with this role can create and edit models and syncs, but their changes must be approved before they are published.
Create a custom draft role
- Go to Settings > Roles.
- Create a custom role.
- Open the Sources or Destinations tab.
- Select
Draft models & syncsfor the relevant resources.
Users with this permission can draft changes but do not see the Publish now option.
Who can publish directly
Some roles can bypass approval and publish directly. For example, users with the Admin or Workspace editor role can save drafts, submit approval requests, or select Publish now.
Any role without the Draft models & syncs restriction can self-publish.
The Workspace draft editor role is the built-in role whose changes must be approved. It is not the only role that can create drafts. Any role with the Draft models & syncs permission can create and edit drafts. Roles that can publish directly can also save drafts voluntarily but still have access to Publish now.
If you use approval flows, we recommend the following role structure:
- Admin — Can approve changes and manage the workspace.
- Workspace editor — Can approve changes and publish directly.
- Workspace draft editor — Can create and edit models and syncs, but changes require approval before publishing.
For more advanced setups, create custom roles that include or exclude the Approve models & syncs permission on model and sync resources.
Create new resources
When you create a new model or sync, the available actions depend on your role:
- Publish now publishes the resource immediately. Only available to roles that can bypass approval.
- Submit approval request sends the draft to one or more approvers for review. You can include a comment.
- Save as draft saves the resource without notifying anyone. You can keep editing and submit it for approval later.
If your role requires approval, you do not see Publish now. You can only submit the resource for approval or save it as a draft.
If a sync uses a model that is still in draft mode, both the model and the sync must be published before the sync can run.
Edit existing resources
Editing existing models and syncs uses the same approval options as creating new resources.
The following changes require approval:
| Resource | Changes requiring approval |
|---|---|
| Model | Query, configuration, and column type changes |
| Sync | Configuration and schedule changes |
If a sync uses a model with unpublished changes, the sync refers to the draft version of the model instead of the published version. Both the model and the sync must be published before the sync can run.
Approve requests
Approvers can view approval requests by selecting View request on the corresponding resource.
When reviewing a request, approvers can choose one of the following actions:
- Approve & publish publishes the new resource or drafted changes.
- Delete draft deletes the draft. New resources or drafted changes are discarded and cannot be recovered.
- Withdraw request removes the approval request but keeps the draft. Users can continue editing and submit it again later.
Any user with approval permission and access to the resource can approve the request, even if they were not selected as the reviewer.
For sync changes, the approval request shows a comparison of changes to the sync configuration. For model changes, the approval request shows changes to the model query.
Who can approve requests
The Approve models & syncs permission controls who can approve requests. By default, all roles except Workspace draft editor and Workspace viewer include this permission:
- Admin
- Workspace editor
- Model + sync editor
- Sync editor
- Source admin
- Destination admin
- Audience editor
To grant or remove approval permissions for a custom role, add or remove the Approve models & syncs permission for the relevant sources or destinations. Users with this permission can use Approve & publish, Delete draft, and Withdraw request when reviewing a draft.