Principle:Langgenius Dify Plugin Settings

Knowledge Sources	Dify
Domains	Plugin_System, Marketplace, Frontend
Last Updated	2026-02-12 00:00 GMT

Overview

Description

Plugin Settings governs the workspace-level configuration of the plugin subsystem, including reference settings (global plugin preferences), auto-upgrade policies, and permission management. This principle establishes a preferences-and-permissions model where workspace administrators can control how plugins behave and who can install or manage them.

The settings layer is separated into three concerns:

• Reference Settings -- Global plugin preferences fetched from and written to a dedicated preferences endpoint. These settings control behaviors such as plugin execution defaults and display preferences.
• Auto-Upgrade Management -- A mechanism to exclude specific plugins from automatic upgrades, giving administrators granular control over which plugins receive updates automatically.
• Permission Management -- A workspace-level permission system that controls which installation sources (marketplace, GitHub, local) are allowed and what roles can manage plugins.

Usage

Plugin Settings are accessed through the workspace administration interface:

• Fetching current settings -- useReferenceSettings retrieves the current ReferenceSetting object from /workspaces/current/plugin/preferences/fetch.
• Updating settings -- useMutationReferenceSettings posts the updated ReferenceSetting payload to /workspaces/current/plugin/preferences/change.
• Excluding plugins from auto-upgrade -- useRemoveAutoUpgrade posts a plugin_id to the auto-upgrade exclusion endpoint.
• Changing permissions -- updatePermission posts a Permissions object to /workspaces/current/plugin/permission/change, controlling installation source restrictions and role-based access.

Theoretical Basis

The Plugin Settings principle draws from several architectural patterns:

• Configuration as a first-class entity -- Rather than scattering plugin preferences across multiple endpoints, the system centralizes them under a ReferenceSetting type with dedicated fetch/change endpoints. This follows the Repository pattern where the preferences endpoint acts as the single repository for plugin configuration state.
• Optimistic query invalidation -- After a mutation succeeds, the useInvalidateReferenceSettings hook invalidates the query cache, forcing a fresh fetch. This ensures the UI always reflects the latest server state without manual cache manipulation.
• Least privilege -- The permission model allows administrators to restrict installation sources (e.g., disabling local file uploads in production environments) and role requirements, following the Principle of Least Privilege for plugin management.
• Explicit exclusion over implicit inclusion -- The auto-upgrade exclusion model defaults to upgrading all plugins and requires explicit opt-out for specific plugins, reducing the administrative burden while maintaining control.

Related Pages

• Implementation:Langgenius_Dify_UseReferenceSettings