Why Dify plugin auto-upgrade needs a written policy
Each Dify integration category can be set to update automatically off, to patch versions only, or to always latest, and a marketplace check runs every 15 minutes by default through ENABLE_CHECK_UPGRADABLE_PLUGIN_TASK. That means a running deployment can pick up a changed model provider, tool or agent plugin without a platform release, the Dify upgrade you planned, or a change ticket. For a regulated team, the setting is a change control question, not a convenience toggle, so the decision belongs in a written policy with one line per category: model providers, tools, agent strategies and any private plugins your team builds.
The policy should state the default for each category, who may change it, and what evidence is kept when a plugin version moves. Patch-only updates still change code that handles prompts, credentials or outbound calls, so teams should confirm with the plugin publisher what a patch release contains before treating it as low risk. Set the marketplace check interval and auto-update mode in the environment file and the integrations settings, then record both in the same change record. Confirm in your own environment whether auto-update is applied per plugin or per category before writing the policy.
The supported path is to pin each plugin to a tested version, promote a candidate version into a staging instance built from the same images and environment file, run the apps and knowledge workflows that depend on it, and only then move the pin in production. Keep the pinned versions in your deployment records so a rollback has a known target. The Dify releases page is the place to track platform changes alongside plugin changes, because a platform upgrade can change which plugin versions your deployment expects.
What changes in Dify and plugins that affects upgrades
This table compares the plugin and platform changes that can alter a running Dify deployment, with the impact of each and the action an operator should take. Read it as a checklist for deciding how much plugin change your environment can absorb between platform upgrades. The main takeaway is that automatic plugin updates and platform releases arrive on separate schedules, so each needs its own pinning decision and its own test.
| Change | Impact | Action needed |
|---|---|---|
| Per-category auto-update: off, patch only or latest | Off holds each plugin at its installed version. Patch only accepts fixes within the same version line. Latest accepts new major and minor plugin versions as they appear. | Set each integration category deliberately, record the choice in change control, and default regulated categories to off or patch only. |
| ENABLE_CHECK_UPGRADABLE_PLUGIN_TASK defaults to true | The platform checks the marketplace for newer plugin versions every 15 minutes, so a permissive category setting can change a plugin without a platform upgrade. | Confirm the value in your environment file, and set it to false if plugin changes must go through your own release process. |
| Roughly monthly minor releases (1.16.0 on July 17, 2026; 1.17.0 on August 25, 2026; 1.17.1 on September 10, 2026) | Platform changes arrive faster than most change windows, so a deployment can fall behind or move forward without a planned test cycle. | Track the releases page, decide which minor versions to adopt, and schedule a staging test for each one you plan to deploy. |
| 1.16.1 agent sandbox network isolation through a Squid proxy | Agent and plugin tool calls that reach outbound addresses may be routed or blocked differently, which can break plugins that worked before. | Test every agent workflow and plugin tool that makes outbound calls, and record which destinations each one needs. |
| 1.16.1 token-based API authentication between services | Internal calls between Dify services and plugin components depend on tokens, so a mismatched or outdated plugin may fail to authenticate. | Confirm each plugin version supports the platform's internal authentication and check logs for rejected calls after upgrade. |
| 1.16.1 sandboxed Jinja2 template rendering | Templates that relied on unrestricted rendering may fail or return different output inside the sandbox. | Review prompts and plugin templates that use Jinja2 and test them in staging before accepting the new platform version. |
| Plugin compatibility with a given platform version | A plugin release can target a different platform version than the one you run, and the relationship is not implied by the version number alone. | Confirm plugin compatibility against the platform release notes before pinning or upgrading either component. |
Choosing off, patch only or latest for each category
Setting a category to off means the marketplace can offer newer plugin versions, but nothing installs until someone chooses to install it. This gives the strongest control over which plugin code runs in production, and it suits categories that touch regulated data, such as model providers that receive prompts, or tools that read internal documents. The trade-off is that the team owns the upgrade cycle, so security fixes wait until a person acts on them.
- Who owns it: the platform owner, with sign-off from the security or compliance lead for categories that handle regulated data.
- Typical categories: model providers carrying sensitive prompts, and custom or privately built tools whose code you control.
- What it risks: delayed security patches and version drift between environments if staging and production are not updated on the same schedule.
- Evidence to keep: a dated change request for each install, the version number before and after, and the name of the approver.
- Operational note: check the release notes for each Dify minor release, because the plugin versions expected by the new platform version may need an explicit update.
Before you rely on off, confirm with your own testing how long a pinned plugin keeps working against the Dify version you run, and record that date in your change calendar.
Patch-only updates let Dify apply newer patch versions of a plugin automatically while holding back larger version changes. This is a middle path for categories where you want bug and security fixes without new features or behavior changes arriving unannounced. It still means code changes without a person reviewing each one, so the question is whether a patch increment is trusted to be a narrow change in your environment.
- Who owns it: the platform team sets the policy, and application owners confirm that their workflows still run after patch releases.
- Typical categories: well-established tools and model providers whose behavior your applications already depend on and have tested.
- What it risks: a patch that alters output format, latency or credential handling can change application results without a review step.
- Evidence to keep: a log of automatic patch installs with the plugin name, old and new versions and timestamps, plus a periodic review of that log.
- Operational note: pair patch-only categories with a regression check on representative workflows, and confirm that your Dify version is compatible with the patched plugin.
For each category on patch only, ask the owner to name the test workflows that must pass after an automatic patch, and confirm where the install timestamps are stored.
Latest mode installs the newest plugin version available in the marketplace, including minor and major changes. It keeps capabilities and fixes current with minimal effort, which can suit low-risk, non-sensitive categories such as formatting or utility tools. In a regulated environment it has the weakest change control, because the code that runs can change between one check and the next without a human decision.
- Who owns it: ideally a named platform owner, with the decision recorded in your change policy rather than left as a default.
- Typical categories: utility tools that do not receive personal data, internal documents or credentials.
- What it risks: breaking changes, altered behavior and new dependencies arriving during business hours, and difficulty explaining which version produced a given output.
- Evidence to keep: the version history for each installed plugin, with a record of who approved the category setting and when it was enabled.
- Operational note: the marketplace check runs on a fixed interval, so a plugin can change between your own audit reviews unless you export version state regularly.
Before enabling latest anywhere, confirm that you can reconstruct which version ran for any given date, and that you can roll back to a prior version if a new release fails.
What to inventory and back up before setting a policy
A plugin upgrade policy only protects you if you know what it will touch. The items below establish what is installed, what depends on it, how to restore it, and where to test changes before they reach production.
Plugin inventory by category
List every installed model, tool, agent strategy, extension and bundle plugin with its current version and the category it belongs to. Dify sets auto-update per category, so the category is the unit you will change. Record the version now so you can tell later whether an automatic change moved a plugin, and whether the move was a patch or a larger jump. Note any privately built plugin, since it may not be in the marketplace at all and will not follow the marketplace policy.
Dependency map of apps and workflows
For each plugin, record which apps, workflows and knowledge base pipelines call its tools or models. A tool used in one customer-facing workflow carries more risk than one used in a sandbox app. Include the workspace, the app owner and the environment where it runs. This map tells you who to notify and which flows to re-test after a plugin changes, and it shows which plugins can be pinned without breaking anything important.
Database and plugin storage backup
Take a backup of the PostgreSQL database and the volumes that hold plugin packages before you change any policy. The database holds app definitions, provider settings and plugin records, and the plugin storage holds the installed package files. Dify recommends a backup before every upgrade, and a policy change can trigger the same kind of change. Test that the backup restores to a scratch host, because an untested backup does not give you a rollback path.
Mirrored test environment
Keep a separate workspace or environment that matches production in Dify version, plugin versions, model provider credentials and key environment variables. Apply each candidate plugin version there first and run the workflows from your dependency map. Use illustrative test prompts with realistic structure but no production data. Promote a version only after the test run passes, and keep the test environment on the same policy as production so you learn how auto-update behaves before it reaches users.
Env file update settings
Review the .env file and confirm the value of ENABLE_CHECK_UPGRADABLE_PLUGIN_TASK. The default is true, which means the marketplace is checked for newer plugin versions every 15 minutes. Set it deliberately for each environment, and record the value in your change log. Also check .env.example after any Dify upgrade for new variables, because a missing setting can change plugin behavior without a visible error.
Named owner for policy changes
Assign one person to approve each change to the auto-update setting for each category, and record who approved it and when. Plugins run inside your deployment with access to the workflows and credentials they serve, so an unreviewed change can reach production. The owner should confirm that the inventory, dependency map and backup exist before approving, and should decide the rollback steps in advance.
How to pin plugin versions in regulated environments
Pinning a plugin version is a change control decision, not a technical toggle. The auto-update setting controls when a plugin changes under a running deployment, so choosing it is the same kind of decision as approving a change window or a release. Before touching the setting, record each approved plugin version, the business owner who accepted it, the technical owner who will test and deploy updates, and the date of approval. Keep this register in your change management system or another controlled location, and update it whenever a plugin is installed, updated or removed. Without that record, an auditor who asks which model provider or tool version a workflow used last quarter will get an answer you cannot prove.
Set the auto-update category for each plugin type according to the sensitivity of the workflows that depend on it. Workflows that handle regulated data, customer decisions or outbound actions are the strongest candidates for off, so that a marketplace update can only arrive through a tested change. Lower-risk categories may suit patch only, which limits changes to patch versions. Check the Dify integrations documentation for how each category behaves in your release, and confirm how the 15-minute upgrade check (controlled by ENABLE_CHECK_UPGRADABLE_PLUGIN_TASK) interacts with a pinned category in your environment before you rely on it. Write down who may override a pin, who approves that override, and what evidence must accompany it, such as a test record and a rollback plan. Each exception should name its expiry date so it does not become a permanent drift from the approved baseline.
The controls an auditor expects, such as evidence of approved versions, change approvals and exception handling, are produced by your organization, and the auditor assesses them. DeployOpen can help prepare that evidence: the version register, the category settings as configured, the exception log and test results from pre-production runs. DeployOpen does not issue audit reports, attestations or certifications. Ask your compliance lead which control framework applies to your AI deployment, and map each pinning rule to the requirement it supports before the scope of work is agreed.
Testing a plugin upgrade before it reaches production
This sequence lets a team trial a plugin auto-upgrade policy in a test environment, confirm that the workflows, knowledge base queries and model calls the business depends on still behave correctly, and only then carry the same policy and versions into production. Each step ends with a check and a point you can roll back to.
Record current plugin versions and export affected apps
Before anything changes, the operator lists every installed plugin in production with its category and exact version, and writes the list into the change record. Next, export each app that depends on those plugins as a YAML DSL file. The exports cover app configuration, workflow nodes, model parameters and prompts, but they do not include third-party API keys, knowledge base content or usage logs, so the operator also backs up the database and file storage volumes as a separate step. The step is done when the version list, the DSL files and a verified backup are stored together and can be restored by someone other than the author.
Set test categories to the policy under trial
In the test environment only, the operator opens the integrations settings and sets each plugin category to the update policy being evaluated: off, patch versions only, or always latest. Production stays on its current setting. The operator also confirms that the test environment has the same plugins installed at the recorded versions, so the trial starts from a known baseline. The step is done when the test environment's settings and installed versions match the change record and differ from production only in the auto-update setting.
Wait for the marketplace check to surface an update
The upgrade check is controlled by ENABLE_CHECK_UPGRADABLE_PLUGIN_TASK, which defaults to true and checks the marketplace for newer plugin versions every 15 minutes. The operator confirms the variable is set as intended in the test environment's configuration, then watches the plugin list for a newer version. If no update appears within a reasonable window, the operator checks whether the plugin has a newer release that matches the chosen policy, since a patch-only setting will ignore minor or major versions. The step is done when the plugin list shows the new version and the change record notes the old and new version numbers.
Run representative workflows and knowledge base queries
The test owner, who should be someone from the business team that uses the apps and not only the operator, runs a fixed set of test cases against the upgraded plugin. The set covers representative workflows, retrieval queries against each knowledge base the plugin touches, and model calls through each provider the plugin supplies. Each case records its expected output and the observed result, including latency and any error messages. Expected outputs should be written before the upgrade so the comparison is not shaped by the new behavior. The step is done when every case has a recorded result and each difference from the baseline is either accepted with a reason or logged as a defect.
Check logs and plugin daemon health
The operator reviews the api, worker and plugin daemon logs for the test window and checks that the plugin loads without repeated errors, that tool calls complete, and that background tasks such as indexing still run. Any new warnings are compared with the baseline captured in step one. The operator also confirms that the upgraded plugin does not change any credential or endpoint configuration that production relies on. The step is done when the log review is written up with no unexplained errors, or with each error assigned to a defect that blocks promotion.
Decide whether to promote the policy and version
The change owner reviews the test cases, the log findings and the open defects, then records one of three decisions: promote the plugin version and the auto-update setting to production, promote the version but keep production on a pinned setting, or hold the upgrade. For regulated environments, the decision record should name who approved it and which policy will apply going forward. The step is done when the decision and approver are written into the change record and the production schedule for the change is set.
Promote or roll back using the recorded versions
If the decision is to promote, the operator applies the same plugin version and policy to production during the agreed window, then reruns a short subset of the test cases to confirm the result. If the decision is to revert, or a production check fails, the operator reinstalls the plugin at the version recorded in step one and sets the category back to its previous policy. If the plugin change has altered stored data or configuration in a way a version reinstall cannot undo, the operator restores from the backup taken in step one, which is why that backup must be verified before the change starts. The step is done when the production test subset passes against the chosen version, or when the recorded version is confirmed running and the restored state has been checked.
What makes plugin upgrade testing take longer
This table lists the factors that lengthen testing before a Dify plugin upgrade reaches production, along with how each one changes effort and what to confirm first. Read it as a checklist for scoping: the more rows that apply to your deployment, the more test cases, environments and reviewer evidence the work will need. Effort depends on the written scope, and a quote follows from that scope.
| Driver | Effect on effort | What to confirm |
|---|---|---|
| Installed plugins and categories | Each plugin adds a version pair to compare and a smoke test; each category set to auto-update widens the set of changes that can arrive unannounced. | Export the list of installed plugins and their current update setting for each category (off, patch only or latest). |
| Apps and workflows that depend on each plugin | Every workflow node that calls a tool or model provider needs a run with representative inputs, so effort grows with the number of dependent apps. | Map which apps and workflows call which plugin, and note which ones run in production without an owner. |
| Custom or private plugins | Owners of private plugins must rebuild and retest them against the new Dify plugin daemon behavior, which DeployOpen cannot do on their behalf. | Identify each private plugin, its owner, and the Dify version range it was built and tested against. |
| Model providers and external systems the test must reach | Test runs need working credentials and network paths to each provider or external tool, and failures often look like plugin regressions when they are connectivity issues. | List every provider endpoint and external system, and confirm test credentials, egress rules and SSRF_PROXY behavior for the test environment. |
| Environments in the promotion path | Each environment in the path (for example development, staging and production) repeats the upgrade check, and differences in configuration or data can hide or create defects. | Confirm how many environments exist, which ones hold production-like data, and whether they run the same Dify version. |
| Evidence the reviewer requires | Change reviewers may ask for version records, test results per workflow, rollback steps and sign-off, and assembling this evidence takes time in every cycle. | Ask the approver which records they need, in what format, and how long they keep them. |
Questions teams ask before changing plugin upgrade settings
Can our team set plugin upgrade policy on its own?
Yes, a Dify administrator can change the per-category update setting and the upgrade check without outside help, and many teams do. The harder part is agreeing who approves a change and who tests it. Before changing anything, confirm which plugin categories your apps depend on, who owns each one, and who signs off when a plugin version changes in production. A partner can help write that policy, build the test run and document the evidence, but the setting itself is a small change. Ask for a written scope if you want outside help with the policy and testing, not just the toggle.
How long does testing a plugin upgrade take?
Testing time depends on how many plugins your production apps use, how many workflows and agents call each one, and how many model providers, tools or data sources sit behind them. A plugin that only handles one model provider with a simple prompt is quicker to check than a tool that writes to an external system. Your test environment also matters: if it is a copy of production with realistic data and credentials, tests take longer to set up but give more confidence. No duration is fixed here, so ask for a timeline in the written scope that lists the plugins, the test cases and the rollback steps.
What does our staff need to provide for plugin upgrade testing?
Three roles make the process work. Plugin owners know what each plugin does, which apps depend on it and what a correct output looks like. A test environment should run the same Dify version, plugin set and model connections as production, with test data in place of live records. A change approver decides whether a tested upgrade goes to production and records that decision. Without these people named, upgrades either stall or happen without review. Your staff also need access to the marketplace or your private plugin source, and to the Dify environment settings that control upgrades.
Is patch-only plugin updating always safe?
No. Patch-only updates limit changes to patch versions, which usually carry fixes rather than new behavior, but a patch can still change how a plugin handles an edge case, a model response or a credential. Treat patch-only as a lower-risk setting, not a safe one. Your apps should still pass a short regression check after a patch update, and you should keep a record of which version each category runs so you can roll back. Confirm with each plugin publisher how they version their releases and what a patch is allowed to change.
If we turn auto-update off, are we exposed to security fixes?
Turning auto-update off does not stop security fixes from being available, but it means someone must decide to take them. With updates off, a vulnerable plugin version keeps running until your team installs a newer one. Set a review rhythm that checks the Dify release notes and plugin changelogs, and define how quickly a security fix must be tested and deployed. The Dify environment reference describes a check that runs every 15 minutes by default (ENABLE_CHECK_UPGRADABLE_PLUGIN_TASK), so the check itself is not the gap. The gap is the approval step. Ask a partner or internal security team to document that step as part of your change process.
Does the 15-minute upgrade check change how plugins update?
The check looks for newer plugin versions in the marketplace every 15 minutes by default, controlled by ENABLE_CHECK_UPGRADABLE_PLUGIN_TASK. It tells the platform that a newer version exists, but what happens next depends on each category's setting. If a category is set to off, the check does not install anything for it. If it is set to patch only or latest, the upgrade follows that rule. In a regulated environment, decide whether the check should run at all, then confirm in a test instance how your chosen settings behave before relying on them. Air-gapped installs need a separate plan because they cannot reach the marketplace.
What should a quote for plugin upgrade policy work include?
A quote should follow a written scope that names the Dify version and deployment type, the plugins and categories in use, the test environment to be built or reused, and the change approval process. It should list deliverables such as the policy document, the pinned versions register, test cases, rollback steps and the evidence captured for each upgrade. Ask whether the price covers one-time setup, recurring upgrade cycles or both, and what a retainer for ongoing testing would include. DeployOpen does not publish a price list, so the quote follows from the scope you agree in writing.
How DeployOpen works on this
DeployOpen plans, implements and documents the plugin upgrade policy for a self-hosted Dify deployment inside infrastructure you control. The work starts with a written scope covering which plugin categories may update, how upgrades are tested, and who approves production changes.
How we scope
- Inventory every installed plugin, its category and the workflows and apps that depend on it.
- Agree in writing which categories run with auto-update off, patch only or latest.
- Define the change approval owner, the test environment and the rollback expectations before work starts.
- Confirm how the 15-minute marketplace check is set and whether it may be disabled in your environment.
How we build
- Configure per-category update settings and pin plugin versions that your change process has approved.
- Set the upgrade check flag in your environment file so behavior matches the written policy.
- Build a staging instance that mirrors production plugins, model providers and environment variables.
- Test each plugin upgrade against representative workflows, knowledge base queries and agent runs before promotion.
How we hand over
- Provide a written policy covering categories, pinned versions, owners and review intervals.
- Document the upgrade test checklist and the evidence record kept for each approved change.
- Walk your platform and security teams through how to pin, unpin and roll back a plugin.
- Hand over configuration files and runbook steps so your team can operate the policy without us.
How we support
- Review new plugin releases against the policy and prepare test results for your approval.
- Support ongoing plugin reviews and upgrades under a retainer, if your team wants continuing help.
- Refresh the pinned versions and test plan when Dify core upgrades change plugin compatibility.
- Confirm the scope, deliverables and timelines in writing before any new support work begins.
