docs+test: supported install/config paths for the plugin (ENG-8351)#106
Merged
Conversation
The Fleet / global deployment section presented hand-writing
~/.claude/settings.json (extraKnownMarketplaces + enabledPlugins) as enough to
install the plugin. Verified in CI that it is NOT: enabledPlugins only enables
an already-installed plugin and extraKnownMarketplaces only registers the
marketplace — neither downloads anything (`claude plugin list` shows nothing
installed, no plugins dir created). This is what caused a customer's fleet
rollout to silently not enable the plugin.
Rewrite the section around the proven one-step CLI installer:
claude plugin install dash0-agent-plugin@dash0 --scope user \
--config OTLP_URL=... --config AUTH_TOKEN=... --config DATASET=...
which installs, enables, AND configures non-interactively. Non-sensitive
values land in settings.json pluginConfigs; AUTH_TOKEN goes to the OS keychain
(.credentials.json fallback on Linux) — verified in CI. Keep the config-file
and env-var approaches as documented alternatives, and call out the SSH→HTTPS
marketplace-clone gotcha that the bare-file path silently hit.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contract tests (ci.yml, no API key needed) pinning the install + config behavior the docs depend on: - A: hand-written ~/.claude/settings.json alone does NOT install the plugin - B: `claude plugin install --config` installs and persists non-sensitive values to settings.json pluginConfigs, AUTH_TOKEN to the secrets store (never settings.json) - C: a ~/.claude/dash0-agent-plugin.local.md config file feeds creds through on-event.sh to a real OTLP request (mock server) These complement the existing marketplace-install steps (official / Dash0 / local-workspace) and the Go unit tests (binary reads CLAUDE_PLUGIN_OPTION_*). README Fleet section reworked to lead with `claude plugin install` + a config file (the supported, customer-validated path), with --config and env vars as documented alternatives, and the "settings.json alone won't install" callout. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contract B asserted on ~/.claude/plugins/cache, but a local/directory marketplace serves the plugin in place and never populates the cache. Switch B to the published marketplace (--config persistence is marketplace-agnostic; PR-code install is covered by the workspace step). Contract C now runs from a clean cwd so the repo's .env/.claude can't override the values under test. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
GuyMoses
changed the title
README: - Replace the non-resolving `ingress.us1.dash0.com` examples with the real placeholder form `https://ingress.<region>.aws.dash0.com`, and tell users to copy their exact endpoint from Dash0 org settings (us1 didn't exist; real ingress is ingress.<aws-region>.aws.dash0.com — verified via DNS) - De-dup: Fleet step 1 references Headless/CI instead of repeating the install commands; Fleet credential bullet points to the config-file format instead of re-showing frontmatter; tighten the "config files don't merge" wording - Headless/CI now points to First-time setup for credentials Tests: Contract C now covers BOTH documented credential mechanisms — a config file and DASH0_*/CLAUDE_PLUGIN_OPTION_* env vars — each verified end-to-end through on-event.sh to a real OTLP request. Job comment maps contracts A/B/C to the documented install/credential options. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…ions - Add the two missing userConfig options (OMIT_IO, OMIT_USER_INFO) to the Configuration table so it lists all 6 declared in plugin.json (they were documented only under Privacy defaults, making the table look incomplete and inconsistent with the env-var/config-file tables). - Add a consistency-checks step asserting every plugin.json userConfig option appears as a README table row, so this can't regress. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
A customer's fleet rollout silently failed to enable the plugin: the Fleet docs implied hand-writing
~/.claude/settings.jsoninstalls it (it doesn't). This PR fixes the docs and adds contract tests so the install/credential behavior the docs depend on can't silently regress.Docs
ingress.us1.dash0.comdidn't resolve. Replaced with the real placeholderhttps://ingress.<region>.aws.dash0.com(verified via DNS: real ingress isingress.<aws-region>.aws.dash0.com, e.g.eu-west-1,us-west-2), plus "copy your exact endpoint from Dash0 org settings".claude plugin install(the supported path), explicit "settings.json alone won't install" callout, SSH→HTTPS note. De-duplicated: Fleet references Headless/CI for the install commands and the config-file format instead of repeating them.Tests —
install-config-contractCI job (no API key needed), mapped to documented paths~/.claude/settings.jsonalone does not install (the "not enough" callout).claude plugin install --config K=V: installs; non-sensitive →settings.jsonpluginConfigs;AUTH_TOKEN→ secrets store, notsettings.json.on-event.shto a real OTLP request (mock), for both a config file andDASH0_*/CLAUDE_PLUGIN_OPTION_*env vars.Marketplace installs (official / Dash0 / local PR-code) are covered by the existing
build-and-teststeps; the binary readingCLAUDE_PLUGIN_OPTION_*by Go unit tests.Tracks ENG-8351.
🤖 Generated with Claude Code