Problem
A repository that publishes both public docs and internal Codex docs cannot be onboarded to Elastic Internal Docs today, because Codex discovery always resolves the public docset.
CodexCloneService.FindDocsetFile searches a fixed order and returns the first hit:
private static readonly string[] DocsetSearchPaths = ["docs/docset.yml", "docs/_docset.yml", "docset.yml", "_docset.yml"];
falling back to a first-match recursive walk. docs/docset.yml therefore always wins.
Concrete case
elastic/kibana publishes its public documentation from docs/ (registry defaults to public, assembled into elastic.co/docs). We want internal developer documentation — component library docs, engineering guides — in docs-dev/ with registry: internal, published only to codex.elastic.dev.
- PR previews work. The repo controls its own workflow, so it can run
docs-builder --path docs-dev.
- Live publish does not. The build in
elastic/codex-environments clones the repo and discovers the docset itself, landing on docs/docset.yml — the public set — and would publish the wrong content to codex.elastic.dev/r/kibana.
There is currently no way to steer this from the consuming repo:
environments/internal/config.yml carries only environment, site_prefix, title and groups; documentation sets come from the link index, and CodexDocumentationSetReference.Path is populated from where discovery found the file rather than from config.codex/build in elastic/docs-actions invokes docs-builder with no path argument and exposes no path input.- No environment variable overrides the documentation path.
Proposal
During Codex clone/discovery, prefer a docset that declares registry: internal, keeping the existing order as the fallback when none does. DocumentationSetFile.LoadMetadata is already called on the discovered file, so the registry value is cheap to read.
Adding docs-dev/docset.yml to the head of DocsetSearchPaths would cover our case specifically, but the registry check seems more principled — it makes intent explicit rather than relying on a folder name, and it does the right thing for any repo that colocates public and internal docsets.
An explicit per-repository path override (in the environment config or the link index) would also solve it, and would additionally let a repo publish internal docs from a nested location.
Impact
Without this, repos with public docs have to move internal documentation into a separate repository, losing colocation with the code it documents.
Problem
A repository that publishes both public docs and internal Codex docs cannot be onboarded to Elastic Internal Docs today, because Codex discovery always resolves the public docset.
CodexCloneService.FindDocsetFilesearches a fixed order and returns the first hit:falling back to a first-match recursive walk.
docs/docset.ymltherefore always wins.Concrete case
elastic/kibanapublishes its public documentation fromdocs/(registrydefaults topublic, assembled into elastic.co/docs). We want internal developer documentation — component library docs, engineering guides — indocs-dev/withregistry: internal, published only to codex.elastic.dev.docs-builder --path docs-dev.elastic/codex-environmentsclones the repo and discovers the docset itself, landing ondocs/docset.yml— the public set — and would publish the wrong content tocodex.elastic.dev/r/kibana.There is currently no way to steer this from the consuming repo:
environments/internal/config.ymlcarries onlyenvironment,site_prefix,titleandgroups; documentation sets come from the link index, andCodexDocumentationSetReference.Pathis populated from where discovery found the file rather than from config.codex/buildinelastic/docs-actionsinvokesdocs-builderwith no path argument and exposes no path input.Proposal
During Codex clone/discovery, prefer a docset that declares
registry: internal, keeping the existing order as the fallback when none does.DocumentationSetFile.LoadMetadatais already called on the discovered file, so the registry value is cheap to read.Adding
docs-dev/docset.ymlto the head ofDocsetSearchPathswould cover our case specifically, but the registry check seems more principled — it makes intent explicit rather than relying on a folder name, and it does the right thing for any repo that colocates public and internal docsets.An explicit per-repository
pathoverride (in the environment config or the link index) would also solve it, and would additionally let a repo publish internal docs from a nested location.Impact
Without this, repos with public docs have to move internal documentation into a separate repository, losing colocation with the code it documents.