Overview
Workflow releases separate the configuration you are working on from the configuration your users receive.
- Draft is the editable version of a workflow.
- Live is the published version that production requests use.
- A revision is an immutable record of a version that was published before.
Saving an edit updates Draft only. It does not change production. To change production, review the Draft and select Publish.
1Edit Draft → Test → Review changes → Publish → Live handles new requestsYour application continues to call the workflow by the same name. Publishing changes the Live version behind that name; it does not require an API change in your application.
Draft, Live, and History
Open a workflow in the Console and use the version selector in the editor header to see its current state.
| Section | What it means |
|---|---|
| Draft | Saved changes that are not yet in production. |
| Live | The revision currently used for new production requests. |
| History | Earlier published revisions you can inspect, restore into Draft, or roll back to. |
When you have unsaved form changes, use Save draft first. After the Draft is saved and differs from Live, users with publish permission can select Publish.
If you decide not to keep a saved Draft, choose Discard draft from the version selector. This replaces Draft with the current Live version. It does not change Live.
Before publishing
Before you publish a workflow, make sure that:
- The workflow is in Production mode. Workflows in Test Mode cannot be published.
- The selected provider and model are available in the project.
- A structured output still matches the response your application expects, if you use one.
- Any workflow called from a backend pipeline has a Live version already and is still active.
- Backend-pipeline links do not form a cycle between workflows in the same project.
- You have saved the edits you want to review.
Test a Draft or earlier version
Use the Playground to test the configuration you intend to use. Select a workflow, then choose a mode under Run:
| Mode | Runs |
|---|---|
| Auto | Draft when it has unpublished changes; otherwise Live. |
| Draft | The saved Draft, without publishing it. |
| Live | The version currently used by production. |
| Historical | A specific earlier revision that you select. |
Use Draft to test a proposed prompt, model, schema, or pipeline change. Use Live as a production baseline. Use Historical when you need to compare a prior version without rolling production back.
For an asynchronous Playground run, ModelRiver keeps the selected configuration with the request while it is queued and while its pipeline callbacks continue. Editing or publishing a workflow later does not switch that in-progress test to a different version.
Review the changes
From the Draft entry in the version selector, select changes from Live. The Diff vs Live dialog has two views:
- Workflow compares the released workflow path and the new Draft side by side.
- JSON shows the underlying field-level changes.
Review more than the field you intended to edit. In particular, check the model and fallback path, system instructions, structured output, cache or session settings, and backend-pipeline steps.
If the Draft has no differences from Live, there is nothing new to publish.
Publish a new Live version
- Save the Draft and review changes from Live.
- Select Publish in the workflow editor.
- Review the current Live version, the Draft revision number, and the change count.
- Read any warnings and review the dependency closure for backend-pipeline workflows.
- Add an optional release note, then select Publish to confirm.
The new revision becomes Live for new production requests. Earlier revisions remain available in History.
Understand publish warnings
Warnings do not necessarily prevent a release. They highlight behavior worth reviewing:
| Warning | What to consider |
|---|---|
| A callback target has a newer Live revision | Decide whether this parent workflow should adopt that dependency now. |
| Response cache is enabled | Existing cached responses can continue to be returned until they expire. |
| Session memory is enabled | Existing sessions keep their earlier memory; new Live traffic uses the published configuration. |
| A callback pin uses an older revision | Confirm that keeping the older dependency is intentional. |
Workflows that call other workflows
When a workflow has a backend-pipeline step that calls another workflow, publishing records the target workflow's current Live revision with the parent release. This is called a dependency pin.
For example, if order_review calls fraud_check, publishing order_review records the specific fraud_check version it was reviewed with. A later fraud_check release does not silently change the already published order_review behavior.
When a dependency moves forward, the parent Draft can show that change during review. Publish the parent again only when you want it to use the newer dependency.
Roll back or restore
Both actions begin from History, but they solve different problems.
| Action | When to use it | What changes |
|---|---|---|
| Rollback | A current Live version needs to stop serving new production requests. | Live moves to the selected earlier revision. The current Draft is not published. |
| Restore as draft | You want to reuse or adjust an earlier version before deciding whether to release it. | The selected revision replaces the current Draft. Live does not change. |
Use rollback for a production recovery. Use restore when an older release is the best starting point for new work. Restoring a revision replaces your current Draft, so save or discard any Draft work you still need before confirming.
When a restored revision used a structured output, ModelRiver relinks the original structure if its schema and example still match. If that structure was edited or deleted, restore clones it with a unique name so other workflows are not affected.
Neither action deletes revision history.
Names, delete, and import
- A workflow name cannot be changed after it is created. The name is the stable address your application uses in API calls.
- Delete deactivates the workflow. Revision history stays on that record.
- You can create a new workflow with the same name after delete. Production resolves the name to the new active workflow.
- Import and create both produce an initial Live revision (typically R1) from the configuration you bring in. Import does not copy revision numbers from the source project.
Permissions
- Organization owners and admins can publish and roll back workflows.
- Editors (and above) can save draft, discard draft, and restore a historical revision into Draft.
- On protected projects, editor access may be limited; owners and admins always have full access.
If you cannot see an action that another teammate can see, check your organization role and project protection settings.
Frequently asked questions
Does saving a Draft change production?
No. Production continues to use Live until you publish or roll back.
Can I test a release before publishing it?
Yes. Save the Draft, then choose Draft in the Playground.
What happens to a request that is already running when I publish?
It continues with the configuration selected when the request started. Publishing changes the version used by new requests.
Can I pin a revision in production API calls?
No. Production API keys always run the Live revision for the workflow name. You cannot select a historical revision or send a header to override Live in production.
Responses may include revision metadata (for example x-modelriver-revision and x-modelriver-configuration-source: live) so you can correlate logs with the version that ran.
Can I go back without losing the newer version?
Yes. Rollback moves Live to an earlier revision without deleting later revisions. You can inspect or restore them from History at any time.
Next steps
- Build a workflow: Create and configure a workflow
- Test mode: Use predictable sample responses during development
- Multi-step pipelines: Connect workflows and backend callbacks
- Import & export: Move workflow configuration between projects