Resolve env-dependent storybook.registry via allow-listed interpolation

[clintandrewhall]

Closes #3485

Why

docset.yml is a committed, static artifact, but storybook.registry is inherently environment-dependent: local serve, per-PR preview, and main/production each need a different URL that varies only in one ref segment. Today contributors hand-edit docset.yml per environment and revert before merge, which is error-prone. The actor that knows the ref at render time is the build/preview layer, not the author at commit time.

What

storybook.registry now supports shell-style environment interpolation with a committed default, so one committed value works everywhere:

storybook:
  registry: ${KIBANA_STORYBOOK_REGISTRY:-https://ci-artifacts.kibana.dev/storybooks/main/storybook-docs/docs_registry.json}

• ${VAR} / ${VAR:-default} resolve with familiar shell semantics. With no env var set (e.g. a main build) the committed default is used byte-for-byte.
• Because docs-builder renders untrusted PR branches, interpolation is restricted to an explicit allow-list (currently KIBANA_STORYBOOK_REGISTRY). Any other name is never read from the process environment — it is left literal and a warning is emitted — so a malicious docset.yml cannot exfiltrate CI secrets such as ${AWS_SECRET_ACCESS_KEY}.
• Graceful degradation: when an environment-supplied registry (e.g. an ephemeral per-PR URL not yet published) is unreachable, the directive falls back to the committed default. A committed/static registry that fails to read remains a hard error so typos and broken paths don't silently drop every embed.

The substitution primitive lives in Elastic.Documentation.Configuration and is repo-agnostic: docs-builder does not know how to construct a Kibana pr-<N> URL; the consumer supplies the variable.

IEnvironmentVariables is threaded through IDocumentationSetContext so configuration resolution is injectable and the set/unset/fallback cases are deterministic in tests.

[coderabbitai]

Warning

Review limit reached

@clintandrewhall, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 25 minutes and 33 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 3f16e2ed-321c-41ad-9d8a-109a97e35722

📥 Commits

Reviewing files that changed from the base of the PR and between 11c3303 and 08611cd.

📒 Files selected for processing (1)

• tests/Elastic.Documentation.Configuration.Tests/ConfigurationFileStorybookRegistryTests.cs

📝 Walkthrough

Walkthrough

This PR implements environment-variable interpolation for configuration values, specifically storybook.registry. It introduces a shell-style syntax (${VAR:-default}) with an allow-list to prevent secret exfiltration in untrusted PR branches. The interpolation engine is integrated into configuration loading, with a fallback mechanism: if an interpolated registry URL is unreachable at runtime, the build gracefully falls back to the committed default rather than hard-failing. All components thread environment variables through the build context via a new IEnvironmentVariables dependency, and comprehensive tests verify allow-listing, fallback behavior, and that disallowed variables are never read from the environment.

Possibly related PRs

• elastic/docs-builder#2910: Earlier PR implementing {storybook} registry support in the same pipeline; this PR extends registry resolution with environment interpolation and fallback semantics.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 6.45% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: implementing shell-style environment-variable interpolation with an allow-list for storybook.registry.
Description check	✅ Passed	The description clearly explains the problem, solution, security considerations, and graceful degradation behavior for environment-dependent storybook.registry configuration.
Linked Issues check	✅ Passed	The PR implementation fulfills all linked issue requirements: shell-style interpolation (${VAR} and ${VAR:-default}), allow-listed variables (KIBANA_STORYBOOK_REGISTRY), security prevention of secret exfiltration, graceful fallback for unreachable registries, injectable IEnvironmentVariables for testability, and comprehensive test coverage including edge cases.
Out of Scope Changes check	✅ Passed	All changes are directly aligned with the linked issue objectives: environment interpolation logic, fallback handling, allow-list enforcement, injectable environment wiring, test updates for deterministic behavior, and documentation additions. No unrelated modifications detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch storybook-registry-env-interpolation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@tests/Elastic.Documentation.Configuration.Tests/ConfigurationFileStorybookRegistryTests.cs`:
- Around line 43-50: The test DisallowedVariable_IsLeftLiteral_AndWarns
currently asserts only that config.StorybookRegistry remains the literal and
does not contain the secret; update the test to also assert that the
DiagnosticsCollector (collector) recorded a warning. After creating config via
CreateConfiguration(...) and before completing the test, add an assertion that
collector contains at least one warning entry (or a specific warning message) to
verify the warning path is exercised.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 433b691f-3bf0-4666-a3da-e958b6a42ba5

📥 Commits

Reviewing files that changed from the base of the PR and between 182938f and 11c3303.

📒 Files selected for processing (15)

• docs/syntax/storybook.md
• src/Elastic.Documentation.Configuration/BuildContext.cs
• src/Elastic.Documentation.Configuration/Builder/ConfigurationFile.cs
• src/Elastic.Documentation.Configuration/EnvironmentInterpolation.cs
• src/Elastic.Documentation/IDocumentationContext.cs
• src/Elastic.Markdown/Myst/Directives/Storybook/StorybookBlock.cs
• tests/Elastic.Documentation.Configuration.Tests/ApiConfigurationTests.cs
• tests/Elastic.Documentation.Configuration.Tests/ConfigurationFileExcludeTests.cs
• tests/Elastic.Documentation.Configuration.Tests/ConfigurationFileStorybookRegistryTests.cs
• tests/Elastic.Documentation.Configuration.Tests/CrossLinkRegistryTests.cs
• tests/Elastic.Documentation.Configuration.Tests/EnvironmentInterpolationTests.cs
• tests/Elastic.Markdown.Tests/Directives/DirectiveBaseTests.cs
• tests/Elastic.Markdown.Tests/Directives/StorybookTests.cs
• tests/Navigation.Tests/TestDocumentationSetContext.cs
• tests/authoring/Framework/CrossLinkResolverAssertions.fs