An error during validation of inbound links breaks the `docs-build` check on the `elasticsearch/9.1` branch

[vishaangelova]

While backporting a PR on the 9.1 branch of the elasticsearch repo, I noticed that the docs-build check on the PR breaks because of a missing anchor (unrelated to the changes in the PR).

The missing anchor was added in PR #133831 on the main branch of the elasticsearch repo, but the PR wasn't backported to the 9.0 and 9.1 branches. The only link I found to the missing anchor is in the docs-content repo in troubleshoot/elasticsearch/file-based-recovery.md.

Does the build break because it tries to validate the links on the main branch of docs-content against the docs on the elasticsearch/9.1 branch?

The backport was auto-merged regardless of the error thanks to the auto-merge-without-approval label added by the backport tool, and the error itself doesn't affect the docs site because we build the 9.x docs from the elasticsearch/main branch.

However, if we're going to have this check on the elasticsearch/9.1 branch, should we fix the error by backporting the PR that introduced the missing anchor?

(FYI: the docs-build check did not run on the backport for the 9.0 branch, so there was no error there.)

[cotti]

AI triage

Automated investigation against the current codebase. A human still needs to confirm before any code change.

Original concern

The docs-build check fails on a maintenance branch (elasticsearch/9.1) because inbound-link validation reports a missing anchor that exists only on elasticsearch/main, even though the broken link is unrelated to the PR and never reaches the live site.

Findings

• Your hypothesis is correct. Inbound validation always pulls each source repo's main/master link reference, regardless of the branch being built. LinksIndexCrossLinkFetcher fetches cross-links via the "Next" content source (src/Elastic.Documentation.Links/InboundLinks/LinkIndexCrossLinkFetcher.cs:13-31), and GetNextContentSourceLinkIndexEntry hard-codes main/master (src/Elastic.Documentation.Links/CrossLinks/CrossLinkFetcher.cs:96-104). So when elasticsearch/9.1 is built, the docs-content main links are validated against the 9.1 local links.json.
• The build runs inbound-links validate-link-reference → CheckWithLocalLinksJson, which reads the locally built links.json (the 9.1 content) and validates every inbound cross-link that targets elasticsearch:// (src/Elastic.Documentation.Links/InboundLinks/LinkIndexLinkChecker.cs:57-111).
• When an inbound cross-link can't resolve against that local links.json (the un-backported anchor), it is reported via collector.EmitError (src/Elastic.Documentation.Links/InboundLinks/LinkIndexLinkChecker.cs:143-155).
• Any emitted error makes the command exit non-zero: ServiceInvoker.InvokeAsync returns 1 whenever collector.Errors > 0 (src/services/Elastic.Documentation.Services/ServiceInvoker.cs:72-76). There is no "warn only" path on this command.
• The CI wiring has no escape hatch. The action just invokes the command (actions/validate-inbound-local/action.yml:4-9), and the Validate inbound links step in elastic/docs-actions .github/workflows/docs-build.yml (lines ~314-320) runs without continue-on-error and with no branch gating — so the failure reds the docs-build check on any branch.
• No fix has landed. The only changes to these files since 2025-09-29 are refactors (CLI migration feat(tooling): migrate docs-builder CLI from ConsoleAppFramework to Nullean.Argh #3202, project merge [1/5] VSA: Merge Elastic.Documentation.Api.* into single project #3333); the branch-selection and fail-on-error logic is unchanged.

Verdict

Needs stakeholder input

The mechanism is working as written, but the intended behavior on maintenance/backport branches is a policy + cross-repo-contract decision, not a contained bug fix. Inbound validation deliberately checks main-branch inbound links against whatever is built locally; on a non-main branch that guarantees false positives whenever main has anchors not yet backported. Choosing the right behavior (skip on non-canonical branches? validate against the matching version branch? downgrade to a warning?) touches build mechanics, the link-index contract, and versioning policy, so it should go to engineering rather than being patched blindly.

Proposal

Open questions for engineering (ai:eng-question):

• Branch scope — Should inbound validation run at all on non-main/maintenance branches? CheckWithLocalLinksJson already computes GitCheckoutInformation but only uses RepositoryName (LinkIndexLinkChecker.cs:60-62); the branch is available if we want to gate on it. Alternatively gate the step in docs-actions docs-build.yml.
• Version matching — Should inbound links be validated against the matching version branch of the source repo instead of always main/master (CrossLinkFetcher.cs:96-104)? This depends on whether the link index publishes per-version links.json for source repos.
• Severity — Should an unresolved inbound link (a link another repo owns, that this PR didn't touch) be a hard failure that blocks merge, or a warning/annotation? Note the team has previously toggled this fatality (Continue-on-error temporarily for validate-inbound-links #627 made it continue-on-error temporarily; Re-enable inbound links validation on publish #669 re-enabled it).

Related issues

Part of the link-checks cluster under meta #949 (open, "[meta] Link checks & Redirects"). #736 (open) requests proactive detection of removed files/URLs used by other products — adjacent but distinct: this issue is a false-positive failure on maintenance branches, not missing detection.

Notes

The backport noted here auto-merged anyway via the auto-merge-without-approval label, so this currently surfaces as red-but-non-blocking noise. Inconclusive on the exact 9.1-branch content (can't inspect that branch here), but the failure mode is confirmed from the code regardless of the specific anchor. Applying ai:eng-question.