Plugins for your organization

Administrators can decide which plugin catalogs people may use, switch individual plugins off everywhere, show a note on every install, and ship plugins pre-loaded on managed machines. All of it is driven by managed policy, which users and repositories cannot override. This page explains each control and how to check that it took effect.

For the general mechanics of policy files, see Managed settings.

Where policy lives

Managed policy is read only from administrator-controlled locations, never from a project folder:

Next to each base file, a settings.policy.d/ folder may hold *.json drop-ins, applied in name order. A later file wins for the same key. A policy file that is not valid JSON stops Syntic Code from starting and names the file; inside a valid file, one bad entry is skipped and reported while the rest still applies.

The plugin keys

These keys count only in managed policy. The same keys in user or project settings cannot loosen or replace them.

Restrict which catalogs people use

How entries are written

Each entry in strictKnownMarketplaces or blockedMarketplaces is one of:

• a source string, written as syntic plugin marketplace add takes it: owner/repo, a git or https URL, or a local path;
• { "hostPattern": "<regex>" }, matched against the source’s host;
• { "pathPattern": "<regex>" }, matched against the source’s path. For a GitHub source, the path is owner/repo.

An entry that cannot be read is skipped; the others still apply.

Allow only your own catalogs

{
  "strictKnownMarketplaces": [
    { "pathPattern": "^acme-corp/" },
    { "hostPattern": "^git\\.corp\\.example$" },
    "partner-co/approved-plugins"
  ]
}

This allows any GitHub repository under acme-corp, anything on the internal git server, and one partner repository. Everything else is refused with a message that names the policy key.

Block specific catalogs

{
  "blockedMarketplaces": ["someone/untrusted-plugins"]
}

A blocked GitHub owner/repo stays blocked when someone writes it another way, such as https://github.com/someone/untrusted-plugins.git or the SSH form. A block entry without a ref blocks every ref of that repository; one that names a ref blocks only that ref.

When the check runs

The catalog check runs before anything is fetched:

• syntic plugin marketplace add and adding a catalog in /plugin;
• every refresh, including the daily background refresh (a forbidden catalog is skipped with a note);
• syntic plugin install, when the plugin’s catalog is now forbidden.

A catalog that was saved before the policy arrived stays in the user’s list but can no longer be refreshed or installed from.

Control matrix

Switch plugins off everywhere

{
  "enabledPlugins": {
    "risky-tool@acme": false,
    "old-helper@partner": false
  }
}

A force-disabled plugin:

• is refused by syntic plugin install before anything is downloaded;
• cannot be turned on with syntic plugin enable;
• does not load, even if it was installed earlier or is loaded with --plugin-dir or from a pre-seeded folder;
• is reported as a startup problem in machine-readable output.

Only an explicit false has an effect. You cannot force a plugin on through policy.

Show a note on every install

{ "pluginTrustMessage": "Plugins run code with your permissions. Use only catalogs from the Platform team." }

After each successful install, the output ends with the note. Use it to point people to your internal guidance.

Pre-load plugins on managed machines and images

For container images, CI runners and managed laptops, set SYNTIC_PLUGIN_SEED_DIR to one or more folders (separated by : on macOS and Linux, ; on Windows). Each folder is a plugin or a folder of plugins. They load in every session after the user’s installed plugins, without being installed:

export SYNTIC_PLUGIN_SEED_DIR=/opt/syntic/plugins

• A leading ~ is expanded to the home folder.
• An installed plugin with the same name wins over a pre-seeded one.
• Pre-seeded plugins go through the same trust checks and enabledPlugins policy as installed ones.
• They do not load in --bare sessions.

For scripted runs that need a plugin installed from a catalog, use --plugin name@marketplace (with --plugin-scope if needed). It installs before the run without prompting and prints results to standard error.

A per-machine trust list

Separately from managed policy, each machine can keep a trust list in ~/.syntic/plugins/policy.json:

{ "trusted": ["formatter", "acme"], "lockdown": true }

• trusted names plugins or whole catalogs.
• With "lockdown": true, only trusted plugins load; others are blocked and reported.
• Without lockdown, untrusted plugins still load and a trust warning is logged.
• SYNTIC_PLUGIN_LOCKDOWN=1 turns lockdown on regardless of the file.
• SYNTIC_TRUSTED_PLUGINS=a,b,c adds names to the trusted list.

This is useful on shared build machines. For fleet-wide rules, prefer managed policy. See also Plugin safety.

Check the rollout

On a managed machine:

syntic doctor

lists the managed policy keys in force and any plugins left off because a dependency is missing or disabled. Then try the paths your policy should close:

syntic plugin marketplace add someone/untrusted-plugins   # should be refused
syntic plugin install risky-tool@acme                      # should be refused

Each refusal names the reason, so users know it is policy and not a broken catalog.

What policy cannot enforce

• It cannot install plugins for users. Combine a pre-seeded folder or a scripted --plugin install with policy instead.
• It cannot set plugin options or secrets. Those stay per user.
• It cannot stop a user from loading a folder of their own with --plugin-dir, though that folder still passes through enabledPlugins and the trust list.
• Plugins recorded in the managed scope are reported but never removed by syntic plugin reconcile --prune.

Troubleshoot policy