[Docs] Clarify that extraKnownMarketplaces requires interactive trust dialog (not available in CI/headless mode)

Resolved 💬 4 comments Opened Dec 4, 2025 by alexey-pelykh Closed Feb 28, 2026

Summary

The documentation for extraKnownMarketplaces does not mention that this feature only works in interactive mode and cannot be used in CI/CD pipelines or headless execution.

Current Documentation

From Plugin Marketplaces documentation:

"When team members trust the repository folder, Claude Code automatically installs these marketplaces and any plugins specified in the enabledPlugins field."

This implies the feature works automatically, but it actually requires the interactive trust dialog which is skipped in print mode (-p).

Suggested Documentation Improvements

1. Add a callout/warning to the extraKnownMarketplaces section

Note: This feature requires the interactive trust dialog. In headless/print mode (-p), the trust dialog is skipped and extraKnownMarketplaces will not be processed. For CI/CD workflows, use claude plugin marketplace add commands instead.

2. Add a CI/CD section to the Plugin Marketplaces documentation

## Using Plugins in CI/CD

The `extraKnownMarketplaces` setting requires interactive trust confirmation 
and is not available in headless mode. For CI/CD pipelines, use these approaches:

### Option 1: Explicit marketplace add
```bash
claude plugin marketplace add ./
claude plugin install my-plugin@my-marketplace

Option 2: GitHub Action inputs

- uses: anthropics/claude-code-action@v1
  with:
    plugin_marketplaces: |
      https://github.com/your-org/marketplace.git
    plugins: |
      plugin-name@marketplace-name

### 3. Cross-reference in Settings documentation

Add a note in the [Settings documentation](https://code.claude.com/docs/en/settings) under `extraKnownMarketplaces`:
> This setting is processed when users accept the workspace trust dialog in interactive mode. It is not available in headless/print mode (`-p`).

## Evidence

Detailed investigation documenting the behavior: https://gist.github.com/alexey-pelykh/566a4e5160b305db703d543312a1e686

## Impact

Users attempting to use `extraKnownMarketplaces` in GitHub Actions or other CI systems will find the feature silently doesn't work, with no indication of why.

View original on GitHub ↗

This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗