How Dify workflow version control and release management keeps live apps safe
Version control in Dify gives a team a way to change a live Chatflow or Workflow app without editing what end users are running. Each app has a current draft that editors work on, a latest version that is the published, live state, and a set of previous versions that can be reviewed or restored. Publishing turns the draft into the new latest version, so the draft is where all experimentation happens and the live app only moves when someone deliberately publishes. The feature applies only to Chatflow and Workflow apps. Agent, chat and completion apps do not get this version history, so their change control has to live somewhere else, such as an export kept in your own repository.
Teams usually need this once more than one person edits an app, once a change to a prompt or model setting can affect customers or staff, or once a change record must show what was live on a given date. Named versions with release notes give reviewers a readable history, and restoring an old version gives operators a rollback path. Confirm two limits before you depend on it. Restoring a version replaces the current draft completely, so any unsaved work in the draft is lost. Old versions can be deleted, except the current draft and latest version, so set a retention rule and confirm who may delete them in your workspace.
Version control also does not cover everything a release touches. It records the app's own configuration in the Dify database, but it does not replace an approval step, a copy of the app outside the instance, or the environment-specific settings that differ between test and production. Plan for those separately. Confirm with your own team what your change process needs to record, then decide how named versions, release notes and DSL exports will fit together for promotion between environments.
What the draft, latest and previous versions do
Dify version control for Chatflow and Workflow apps separates work into three states. The current draft is the working copy that builders edit in the canvas. The latest (live) version is the published release that end users and API callers receive. Previous versions are the snapshots kept from earlier publishes. Publishing turns the current draft into the new latest version, so the draft is the only place where changes accumulate before they reach users. Before you adopt this model, confirm with your own test workspace which app types expose the version panel in your Dify release, since the docs limit versioning to Chatflow and Workflow apps.
Naming each version and writing release notes is the cheapest control in the workflow. A name such as the change ticket or the prompt revision gives reviewers a stable reference, and release notes record what changed in nodes, prompts and model settings. This matters most when a human reviewer or a compliance lead must later explain why an answer changed on a given date. Set a team rule that no publish happens without a name and a note, and agree on who may publish, because the version record only tells you what was published, not whether it was approved.
Restoring a previous version replaces the current draft completely, so any unsaved or unpublished draft work is lost. Treat restore as a destructive action: export the draft as DSL or copy the canvas first if anyone may still need it. Deleting old versions is also limited: you can remove previous versions, but never the current draft or the latest version. Plan retention for previous versions as part of your change record, and keep DSL exports of published releases outside the platform if you need them after a version is removed.
Which version control practice fits which change
This table compares four practices for changing a Dify chatflow or workflow app, with the scope each one covers and the risk it carries. Read each row against the kind of change you are making, then check what the practice leaves out before relying on it for promotion or recovery.
| Practice | When it fits | What it does not cover | Main risk |
|---|---|---|---|
| Publish after each reviewed change | Routine prompt, node or logic edits on a Chatflow or Workflow app that a second person has tested in the draft | Previous versions are only kept until deleted, and it does not move the app to another environment | Publishing an untested draft replaces the live version for every user of the app |
| Name a version and add release notes | Release points you may need to identify later, such as a change that affected answers or a prompt set agreed with a business owner | Knowledge base content, third-party API keys and usage logs are not part of the version | Vague names or empty notes make it hard to tell which version is safe to restore |
| Restore an earlier version as rollback | Fast recovery when the latest published version misbehaves and the last good version is still in the version list | Deleted versions cannot be restored, and it does not roll back knowledge base content or logs | Restoring replaces the current draft completely, so unsaved draft work is lost |
| Export DSL for promotion | Moving an app from a test workspace or instance to production, or keeping an app definition in source control | Third-party API keys, knowledge base content and usage logs are left out, so these must be reconfigured | Missing credentials or knowledge connections cause failures after import that look like app defects |
| Keep DSL files under version control | Teams that need a review trail, diffs between releases and a reproducible copy of each app definition | Live state in the running instance and data stored outside the app definition | Teams assume the repository is a full backup and skip backups of the database and file storage |
Setting up a release process for Dify apps
This sequence turns ad hoc edits to a Dify chatflow or workflow into a repeatable release path, where every live version is named, documented, traceable to a DSL export in version control, and checked in a non-production instance before it reaches users.
Confirm the app is a Chatflow or Workflow
Open the app in the Dify console and check its type. Version control in Dify is available only for Chatflow and Workflow apps, so the release process below applies only to those types. For other app types, agree a separate change method with the app owner, such as a DSL export taken before each edit. Done when the app type is written in the release record and the owner has confirmed the process applies. If the team also runs Community edition, confirm which workspace roles can publish, since that decides who carries out later steps.
Agree naming and release-note conventions
Before the first publish, agree in writing how versions are named (for example, a number tied to your change ticket or a date-based label) and what each release note must contain: the change, the model or knowledge base affected, the test cases run and the approver. Dify lets you name versions and attach release notes, so the convention lives in the note text rather than in a separate system. Done when the convention is in your team's runbook and the approver has signed off on it.
Publish the draft as a named version
The editor works on a current draft. Publishing turns that draft into the new latest version, which is the version end users and API callers receive. Before publishing, run the draft against your test inputs in the debug panel and confirm the outputs match the expected behavior. Then publish, give the version the agreed name and enter the release note. Done when the version list shows the new latest version with its name and note, and the previous latest version is still listed as a prior version.
Export the DSL and store it under version control
Export the published app as a YAML DSL file and commit it to your Git repository with the same version name in the commit message. The export carries app configuration, workflow nodes, model parameters, prompts and knowledge base connections, but not third-party API keys, knowledge base content or usage logs, so those must be restored or reconnected in each target environment. Done when the commit exists, the DSL file opens and matches the published workflow, and the repository records who approved the release.
Test the promoted app in a non-production instance
Import the committed DSL file into a non-production Dify instance or workspace, using the import flow in the Dify console. Recreate the secrets and knowledge base connections the export left out, then run the agreed test cases and compare results with the production version. Check that model providers resolve and that the release note still describes the behavior you tested. Done when the test results are recorded against the version name and an approver has accepted them. If results differ, stop and return to the draft rather than publishing again in production.
Restore an earlier version only through the draft
If a live version misbehaves, restore an earlier version to the draft. Restoring replaces the current draft completely, so save any unpublished work first, because it will be lost. Then confirm the restored draft matches the expected version by comparing its configuration with the DSL file for that version and running the test cases again. Only after that check should you publish it as a new named version, so the rollback itself appears in the version history. Done when the new latest version has a release note that names the version it restores.
Keep old versions only as long as the policy allows
Dify lets you delete old versions, except the current draft and the latest version. Before deleting any version, confirm it is no longer needed for an audit, an incident review or a rollback window set by your policy, and confirm its DSL file remains in version control. Deleting from Dify does not remove the committed export. Done when the deletion is recorded in the release log and the matching DSL file is still retrievable from the repository.
Promoting apps between self-hosted environments
The Community edition is free for self-hosting but is limited to a single workspace. That means there is no separate workspace to act as staging inside the same installation, so a promotion path has to be built with a different approach. Teams on this pattern usually keep the live app in the one workspace and use the version control features to draft, name and publish changes, then roll back by restoring an earlier version if a release misbehaves. Promotion to a separate environment is a different question and is covered in the other tabs.
- Draft and publish cycle: Edit the draft, then publish it to make it the new latest version with a name and release notes.
- Restore for rollback: Restoring an old version replaces the current draft completely, so publish the restored state only after you have checked it.
- Limit of one workspace: Separating test and production data inside one workspace relies on naming and access discipline, not on isolation.
- Export as a backup: Keep DSL exports of key apps under version control so you can recreate an app if the workspace is damaged.
Confirm with your team how many workspaces your edition and license allow before you design the process around them.
Some organizations run separate self-hosted Dify instances for development, test and production, each on infrastructure they control. Promotion then means exporting an app from one instance as a YAML DSL file and importing it into another. The DSL file carries app configuration, workflow nodes, model parameters, prompts and knowledge base connections. It does not carry third-party API keys, knowledge base content or usage logs. Every credential, document and log must therefore be re-established in the target instance before the app can run there.
- What the file carries: Workflow structure, prompts, model parameters and knowledge base connections travel with the export.
- What the file leaves out: Third-party API keys, knowledge base content and usage logs stay behind.
- Re-establishing credentials: Add model provider credentials and tool authorizations in the target, using that environment's secret handling.
- Re-populating knowledge: Connections are exported, but the documents must be loaded again, which can change retrieval results.
- Version history: Version history inside the source instance does not move with the DSL, so record release notes outside it.
For illustrative purposes, a team that promotes a workflow from test to production will still need to add production model keys and confirm that the knowledge base is populated before testing.
The Dify pricing page lists the self-hosted Enterprise edition as adding SSO, multiple workspaces, advanced security, a commercial license and professional support, with custom pricing. Multiple-workspace and admin features are therefore part of the Enterprise tier, not the Community edition. A multi-workspace layout can separate development, staging and production inside one platform, but the export and import mechanics are the same DSL files, and the same credentials and knowledge content must still be re-established in each workspace.
- Tier confirmation: Confirm with the vendor which workspace, SSO and admin features apply to the license you would buy.
- Separation of duties: Workspace separation can give different people access to staging and production, which is useful for release approvals.
- Credential scope: Model keys and secrets should be scoped per workspace, so a staging key does not reach production.
- Promotion record: Keep DSL files, release notes and approvals in your change management system.
- Admin tooling: Ask whether the Enterprise edition offers any automation for export and import before you build your own scripts.
Before committing to a pattern, confirm which features your chosen edition includes in writing, because the free and licensed tiers differ in exactly these areas.
Risks in release management that teams underestimate
Dify version control gives teams drafts, named versions and restore, but several of its behaviors are easy to misread under deadline pressure. The cards below cover the places where a published change, a restored draft, an exported file or a version history can hide a problem until it reaches production.
Restoring overwrites the draft
Restoring an earlier version replaces the current draft completely, so any unpublished edits in progress are lost. Before restoring, copy the current draft's prompts, node settings and variables into a note or an exported DSL file, then restore. Make this a written step in your rollback runbook so an on-call editor does not discover the loss later.
Deleting versions removes rollback points
Old versions can be deleted, except the current draft and latest version. Once a version is removed, you cannot restore to it, which can leave you with no known-good state after a bad release. Set a rule that every published version carrying a production change keeps a named release note, and that deletion requires the owner's sign-off. Confirm whether your team also keeps DSL exports as an off-platform copy.
Prompt and model changes skip code review
Editing a prompt, switching a model or changing a temperature setting alters application behavior without touching code, so it often bypasses the review a developer change would get. Treat these fields as production code: require a second editor to review the diff against the previous version and run a fixed set of test questions before publishing. Confirm which settings your model provider changes with its own version updates.
Exports can carry sensitive configuration
A DSL export includes app configuration, workflow nodes, model parameters, prompts and knowledge base connections. It excludes third-party API keys, knowledge base content and usage logs, but prompts and connection details can still reveal internal systems and business logic. Store DSL files in a restricted repository, review them for embedded internal URLs or customer-specific wording before sharing, and apply the same access rules you use for source code.
Credentials must be re-entered after import
Because API keys are not included in a DSL export, an imported app in another environment will not call its model providers or tools until someone re-enters the credentials. Plan the import as a checklist: connect each model provider, re-authorize each tool, reattach each knowledge base and confirm the connection in a test run before opening the app to users. Keep this list with the release record so the promotion is repeatable.
Version history is not an approval record
Named versions and release notes show what changed and when, but they do not record who approved a release or what evidence supported it. If your governance requires recorded sign-off, keep an approval log outside the platform that links each published version name to the reviewer, the test results and the date. Confirm with your compliance lead what evidence an auditor will ask for before relying on platform history alone.
Questions teams ask before running Dify release management
Is Dify version control enough to serve as a regulated change record?
No. Dify's versioning gives you named versions, release notes and a restorable history inside the app, which is useful evidence of what was published and when. It does not on its own give you approvals, reviewer identity records, change tickets or retention controls that an auditor may expect. Those usually come from your change management system, with Dify versions and exported DSL files referenced from each change record. Confirm with your compliance lead which evidence they need, then design the record around it. DeployOpen prepares systems and evidence for assessments but does not issue audit reports or attestations.
How much effort does a Dify release process take, and what drives it?
The effort depends mostly on how many apps are live, how many people edit them, and how strict your approval path is. Publishing in Dify is a single action, so most of the work sits around it: agreeing who may publish, writing release notes that a reviewer can act on, testing the draft against representative inputs, and recording the decision. Teams with many apps and several editors need a naming convention and a review cadence early. Ask any partner to price the process against your written scope, with the number of apps, environments and approval steps stated.
What must our team provide before we start release management?
Your team needs to supply four things: named environments (at minimum a test and a production instance), an owner for each app who approves publishing, a storage location for exported DSL files under version control, and a short rule set for release notes and version names. Access to the Dify workspaces and to your repository must be arranged in advance. Decide who can restore a version, since restoring replaces the current draft. Confirm these responsibilities in the written scope so that gaps show up before go-live rather than during an incident.
Can our own engineers run Dify release management without a partner?
Yes, if you have someone who can own the process and the surrounding tooling. The Dify features themselves are available in the self-hosted Community edition, which is limited to a single workspace, and the version history is built into each Chatflow and Workflow app. What takes more skill is the DSL pipeline, repository discipline, multi-environment promotion and the upgrade work that touches stored apps. A partner is useful when you need the process designed, the environments built and the team trained at once. Your own team is a reasonable choice when the scope stays small and one owner can carry it.
What happens to the current draft when we restore an old version?
Restoring a version replaces the current draft completely, so any unpublished edits in the draft are lost. Dify's documentation describes this behavior, so treat it as a hard rule in your process. Before restoring, export the current draft as DSL or publish it as a named version, so the work can be recovered. Restoring also does not change the live version until you publish again, which gives reviewers a chance to test the restored content first. Write this step into your rollback procedure so operators do not discover it during an outage.
How do Dify upgrades interact with versions that are already stored?
Stored versions and DSL exports are your rollback material, so an upgrade should not start until you have a backup. Dify's Docker Compose documentation recommends a backup before every upgrade, follows each release with an upgrade guide for the target version, and asks operators to check the example environment file for new variables. Minor releases arrive roughly monthly, so a planned upgrade window and a rehearsal in a test instance are sensible. After an upgrade, open a sample of previously published apps, confirm that the live version runs, and re-export DSL to compare. Ask your partner or internal owner to document this check in the runbook.
Where do DSL files belong, and how do they support promotion between environments?
DSL files belong in a version control repository that your organization controls, so each change has an author, a diff and a review. Exports carry app configuration, workflow nodes, model parameters, prompts and knowledge base connections, but not third-party API keys, knowledge base content or usage logs. That means secrets and knowledge data must be re-attached in each target environment, and your promotion checklist should say so. Keep the Dify version name and release note in the commit message to link the two records. Confirm the import behavior in your own test instance before relying on it for production.
How Dify upgrades affect versions and DSL files
Plan every Dify upgrade as a change to your version history, not just a new image. Dify minor releases arrive roughly monthly: 1.16.0 followed on July 17, 2026, 1.17.0 on August 25, 2026 and 1.17.1 on September 10, 2026, according to the Dify releases page on GitHub. Each release can change the app configuration that your named versions and DSL exports depend on. The Docker Compose documentation recommends a backup before every upgrade and advises checking .env.example for new variables after the upgrade. Confirm with the upgrade guide for your target version whether any database migration touches workflow data before you schedule the change.
Keep DSL exports as a second recovery path that does not depend on the instance database. Version history lives in the same database as the rest of your deployment, so a failed upgrade or a restore of that database can take your published versions with it. A DSL file for each production app, stored in version control with its release notes, lets you recreate the app in a clean instance. Remember that the export carries app configuration, workflow nodes, model parameters and prompts, but not third-party API keys, knowledge base content or usage logs, so the restore also needs your credentials and knowledge sources.
Before you upgrade production, import your existing DSL files into a staging instance running the target version. Open each imported app, confirm that its draft and latest version behave as expected, and run a few representative conversations or workflow executions. Check that model providers, knowledge base connections and tool references resolve after import. Record any differences in your change ticket, and decide in advance whether a failed test means you hold the upgrade or roll back the staging restore and try again after the next minor release.
