Docset name falls back to `unknown-<dir>` when `--path` points below the git root

[clintandrewhall]

Describe the bug

When --path points at a docset that is not at the repository root, git checkout information is reported as unavailable even though the build is running inside an ordinary git checkout. DocumentationSet.Name then falls back to unknown-<sourceDirName>, and the site renders that string as the docset label.

The cause is that the --path value doubles as the ceiling for the git-root search, so the upward walk can never leave the docset directory:

https://github.com/elastic/docs-builder/blob/main/src/Elastic.Documentation.Configuration/Builder/BuildContext.cs#L114-L116

(DocumentationSourceDirectory, ConfigurationPath) = Paths.FindDocsFolderFromRoot(ReadFileSystem, rootFolder);

DocumentationCheckoutDirectory = Paths.FindGitRoot(DocumentationSourceDirectory, ceiling: rootFolder);

FindGitRoot starts at DocumentationSourceDirectory and is bounded by rootFolder, which is the --path value. When the docset lives below the git root, .git sits above that ceiling, so DocumentationCheckoutDirectory is null, Git becomes GitCheckoutInformation.Unavailable, and Name takes the fallback branch:

Name = Context.Git != GitCheckoutInformation.Unavailable
    ? Context.Git.RepositoryName
    : Context.DocumentationCheckoutDirectory?.Name ?? $"unknown-{Context.DocumentationSourceDirectory.Name}";

Observed on a Codex preview for elastic/kibana, built with docs-builder 1.33.0 through elastic/docs-actions codex-preview.yml with path: docs-dev. The build log shows it plainly, and the rendered page carries unknown-docs-dev as the site label in the top left:

info ::DocumentationGenerator:: Created documentation set for: unknown-docs-dev

Two effects beyond the label, both from the same null DocumentationCheckoutDirectory:

• HtmlWriter gates the per-page GitHub edit URL and the GitHub source URL on it being non-null, so those links are dropped from every page.
• links.json records Origin as the Unavailable sentinel (branch, remote and ref all "unavailable") rather than the real branch and commit.

This is specific to builds that pass --path. codex build is unaffected, because it constructs GitCheckoutInformation explicitly from the clone (RepositoryName = checkout.Reference.Name) and roots the BuildContext at the repository directory, so the live site shows the correct name. That makes it a preview-only discrepancy, which is also why it is easy to miss.

It should affect any repository whose docset is not at the root. Among repos currently wired up to codex-preview that is security-team (docs-codex/), synthetics-service (docs-v3/), platform-engineering-productivity (new-docs/), infra (docs/resilience-team/) and kibana (docs-dev/).

This is not the same as #3136, which was about scope-root access to .git from a worktree.

Expected behavior

With the docset below the git root, the name resolves to the repository name (kibana in this case) and the GitHub edit/source links are emitted, matching what the same content produces when built by codex build.

The two concerns look conflated: --path is meaningful as the content scope root, but using it to bound git discovery means the enclosing repository becomes invisible precisely when the docset is nested. Letting git discovery walk to the enclosing repository, while leaving the content scope root where it is, would fix it — though the scope-root validation that produced #3136 suggests that walk needs to stay read-only and tolerate .git being a file or a link.

Steps to reproduce

1. In a git checkout, place a docset in a subdirectory, for example docs-dev/docset.yml.
2. Run docs-builder --path docs-dev --output ./.artifacts/docs/html.
3. Observe Created documentation set for: unknown-docs-dev in the log, and the same string as the site label in the rendered output.

Reproduced with docs-builder 1.33.0.

Tooling

• docs-builder
• migration tooling

[clintandrewhall]

#3789 looks like it fixes this — it separates the docset anchor from the checkout resolution, replaces the ceiling with maxParents, and BuildContextDocumentationCheckoutDirectoryTests asserts that --path /repo and --path /repo/docs converge. I have left a note there about elastic/infra, whose docset is two levels below the root and so falls outside the default maxParents: 1.

Worth recording here that the third effect I listed — links.json recording the Unavailable sentinel — is not a cosmetic sibling of the other two. It is the one that keeps the repository off codex.elastic.dev entirely.

origin.name and origin.branch are the only source of the key in internal/link-index.json. From update-link-index.js in elastic/codex-link-index:

indices[environment].repositories[origin.name][origin.branch] = entry;

and CodexCloneService.CloneRepository builds the clone URL straight from that key:

var gitUrl = GetGitUrl($"elastic/{repoName}");
var gitRef = fetchLatest ? entry.Branch : entry.GitReference;

So origin.name: "unavailable" does not degrade the entry, it makes one that can never resolve to a repository. The current state for Kibana: internal/elastic/kibana/links.json carries the sentinel, internal/link-index.json has 70 repositories and no kibana, and Kibana's internal docset does not appear on codex.elastic.dev at all — even though codex build itself is unaffected and would render it correctly the moment it were cloned.

That also makes the ordering matter. processFile only skips on a falsy origin:

if (!origin?.name || !origin?.branch) {
  console.warn(`Warning: Missing origin.name or origin.branch in ${filePath}, skipping`);
  return indices;
}

"unavailable" is a truthy string, so a workflow_dispatch rebuild of codex-link-index run before the fix ships would happily create repositories.unavailable.unavailable, and every subsequent codex build would try to clone elastic/unavailable. removeByPath only fires for deleted files, so that entry would outlive the fix and need deleting by hand. Cleanest to land #3789 first and leave the index alone until then.

One more thing for whoever validates this after the fix ships. Re-registering is not automatic: codex-preview.yml's check job gates everything on any_modified and ignores .github/**, so a consuming repo needs a commit that actually touches its docs path before a corrected links.json is published. For Kibana that means a real docs-dev/ change on main, not just a workflow bump.

---

Generated with Claude Opus 5.

[Mpdreamz]

Confirming the closure chain end-to-end: #3789 (now with 8fcf6252a) fixes the infra gap you flagged — DocumentationPathsResolver now widens MaxParents to at least the distance between the invocation root and the resolved docset anchor, so docs/resilience-team/docset.yml (two levels down, no --path) resolves its checkout instead of falling outside the default maxParents: 1.

That also closes the third effect you called out here, since it isn't cosmetic — GitCheckoutInformationFactory.Create only ever gets called with a real, in-scope .git once CheckoutDirectory resolves successfully. Before this fix, a null/mis-bounded checkout meant Git fell back to GitCheckoutInformation.Unavailable, which is exactly the sentinel that turns into origin.name: "unavailable" / origin.branch: "unavailable" in links.json. With checkout resolution now succeeding for all five repos you listed (kibana, security-team, synthetics-service, platform-engineering-productivity, infra), none of them should produce that sentinel anymore, which per your writeup is what actually keeps a repo off codex.elastic.dev — added AnchorTwoLevelsBelowInvocationRoot_StillResolvesCheckoutAtGitRoot to DocumentationPathsResolverTests asserting Git.IsAvailable is true for the infra shape specifically.

Recording your two operational notes here since they're outside anything code in this repo can enforce:

• Don't run a workflow_dispatch rebuild of codex-link-index until Fix site name and git info when --path points to docs subfolder #3789 has shipped, to avoid baking in repositories.unavailable.unavailable.
• Re-registration per consuming repo isn't automatic — codex-preview.yml's check job gates on any_modified and ignores .github/**, so each of the five repos needs a real commit touching its docs path (not just a workflow bump) after the fix lands before its corrected links.json gets published.