How to Configure Plane Settings: Complete Guide to Instance, Workspace, and Profile Management

Plane organizes configuration into three distinct layers—Instance, Workspace, and Profile—each managed through specific UI entry points in the React frontend and backed by dedicated Django API endpoints and MobX state management.

Configuring Plane settings in the makeplane/plane repository requires navigating its hierarchical architecture that separates global instance controls from workspace-specific defaults and personal user preferences. This system implements distinct React components, custom hooks, and backend serializers to handle everything from SMTP configuration to API token generation.

Understanding Plane's Three-Layer Settings Architecture

Plane divides configuration into Instance, Workspace, and Profile settings, each serving different administrative scopes and user roles.

• Instance Settings: Global configurations including email SMTP, authentication providers, and feature flags. Accessible only to instance administrators via the God mode panel as noted in the root README.md.
• Workspace Settings: Workspace-wide defaults such as default issue types, webhook URLs, and member invite policies. Managed through the gear icon in apps/web/core/components/workspace/sidebar/workspace-menu-header.tsx.
• Profile Settings: Personal preferences including notification settings, password management, and API tokens. Accessed via the user avatar menu defined in apps/web/core/components/workspace/sidebar/user-menu-root.tsx.

The backend persists these layers differently: Instance settings use Django's settings module and the Instance model, while workspace and profile settings rely on the WorkspaceSerializer and user-specific endpoints.

Configuring Instance Settings (God Mode)

Instance administrators configure global behavior through the God mode interface.

1. Navigate to Settings → Instance from the God-mode sidebar (visible only to users with instance admin privileges).
2. Toggle services such as email SMTP or authentication providers.
3. Changes persist immediately to the Django settings model and the Instance database table.

This layer controls deployment-wide features and requires direct database access for initial setup.

Managing Workspace Settings

Workspace settings define defaults for all projects within a workspace and are managed through a dedicated drawer interface.

Accessing the Workspace Settings Drawer

The entry point resides in apps/web/core/components/workspace/sidebar/workspace-menu-header.tsx. Click the gear icon in the workspace sidebar header to open the settings drawer.

The drawer renders categories defined in apps/web/core/components/settings/workspace/sidebar/item-categories.tsx, including tabs for General, Members, Webhooks, Integrations, and Import/Export.

Saving Workspace Configuration Changes

Updates flow through the useUserSettings hook defined in apps/web/core/store/user/settings.store.ts. When modifying workspace properties:

// Example: Updating a workspace webhook URL
await fetch(`/api/v1/workspaces/${workspaceId}/webhooks/`, {
  method: "PATCH",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ url: newWebhookUrl }),
});
await fetchCurrentUserSettings(); // Refresh the MobX store

The hook synchronizes the currentUserSettings observable across all components, ensuring UI consistency after updates.

Customizing Profile Settings

Personal configuration manages notification preferences, security credentials, and API access.

Navigating Profile Settings Categories

Open the profile modal via the user avatar menu (the Settings icon in apps/web/core/components/workspace/sidebar/user-menu-root.tsx). The sidebar categories render through apps/web/core/components/settings/profile/sidebar/item-categories.tsx, offering tabs for General, Preferences, Security, and API Token.

Updating Security and API Credentials

Security updates use dedicated endpoints. For password changes:

await fetch("/api/v1/users/me/password/", {
  method: "POST",
  body: JSON.stringify({ old_password, new_password }),
});

API tokens and notification preferences follow similar patterns, updating the currentUserSettings observable in the MobX store after successful requests.

How the Settings Data Flow Works

Plane's React frontend implements a centralized state management pattern for settings:

1. Fetching: The useUserSettings hook calls GET /api/v1/users/me/settings/ on application load, storing results in the currentUserSettings observable.
2. Storing: The MobX store in apps/web/core/store/user/settings.store.ts provides reactive data to all UI components, including the workspace drawer and profile modal.
3. Updating: Components call fetchCurrentUserSettings() after mutations to refresh the observable and trigger re-renders.
4. Persistence: The backend processes updates through Django serializers—InstanceSerializer for global settings and WorkspaceSerializer for workspace data.

Loader components in apps/web/core/components/ui/loader/settings/*.tsx display loading states while data fetches.

Key Source Files for Settings Management

File Path	Purpose
apps/web/core/store/user/settings.store.ts	MobX store managing currentUserSettings and fetch/update helpers
apps/web/core/components/workspace/sidebar/workspace-menu-header.tsx	UI entry point for workspace settings (gear icon)
apps/web/core/components/workspace/sidebar/user-menu-root.tsx	UI entry point for profile settings (avatar menu)
apps/web/core/components/settings/workspace/sidebar/item-categories.tsx	Renders workspace settings navigation tabs
apps/web/core/components/settings/profile/sidebar/item-categories.tsx	Renders profile settings navigation tabs
apps/web/core/components/ui/loader/settings/*.tsx	Loading components for settings async operations
packages/types/src/settings.ts	TypeScript type definitions for settings objects

Summary

• Plane uses a three-layer architecture separating Instance (global), Workspace (team), and Profile (personal) settings.
• Instance settings require God mode access and modify Django configuration directly.
• Workspace settings are accessed via the gear icon in workspace-menu-header.tsx and managed through useUserSettings.
• Profile settings are reached through the user avatar menu and handle credentials via dedicated API endpoints.
• All settings rely on the MobX store in settings.store.ts to maintain synchronized UI state across the application.

Frequently Asked Questions

How do I access God mode to configure instance-wide settings in Plane?

God mode is available exclusively to instance administrators. Navigate to Settings → Instance from the God-mode sidebar, which allows configuration of global email SMTP, authentication providers, and feature flags that apply to the entire Plane deployment.

Where are user settings stored in the Plane frontend codebase?

User settings are stored in the MobX observable currentUserSettings defined in apps/web/core/store/user/settings.store.ts. The useUserSettings hook provides access to this store throughout the React component tree, ensuring consistent state across the workspace drawer and profile modal.

What API endpoint updates workspace configuration in Plane?

Workspace settings are updated via PATCH /api/v1/workspaces/:id/ endpoints. After modifying workspace properties such as webhooks or member policies, the frontend calls fetchCurrentUserSettings() to refresh the MobX store and synchronize the UI with the latest server state.

How do I programmatically update my password or API tokens in Plane?

Profile security settings use dedicated endpoints such as POST /api/v1/users/me/password/ for password changes. These mutations are handled in the profile settings pages found in apps/web/core/components/settings/profile/content/pages/, and automatically refresh the user settings store upon success.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}