[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 andextraKnownMarketplaceswill not be processed. For CI/CD workflows, useclaude plugin marketplace addcommands 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.This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗