Buildkite: Skip PR builds for non-legacy branches

[reakaleek]

What

Make the required buildkite/docs-build-pr check exit 0 early (reporting success without building) when a PR targets a branch that no longer carries legacy AsciiDoc docs.

Why

As docs migrate from this legacy AsciiDoc system to docs-builder, PRs targeting already-migrated branches (stack main/9.x, ECK 3.x, etc.) still trigger the required check and run a useless build. We want those to go green instantly. The check can't simply be removed because it's required.

This supersedes #3233, whose single regex ^([0-8])\.[0-9]+$ broke non-stack-versioned doc sets, as reviewers flagged:

• ECE (cloud) uses milestone branch names (ms-119, ms-105…) → matched nothing → would have wrongly skipped every ECE build.
• ECK (cloud-on-k8s) is legacy only on 2.x/1.x/0.x; 3.x lives in docs-builder but matched ^[0-8]\. → would have wrongly built.

How

• New .buildkite/scripts/legacy_branches.pl derives each repo's legacy branch set directly from conf.yaml — reusing the build's own YAML::LoadFile parser and the branch-resolution convention from lib/ES/Book.pm / lib/ES/BranchTracker.pm (LHS branch keys, map_branches, exclude_branches). It maps the GitHub repo name to the conf repo key via the top-level repos: URL map (handles cases like esf → elastic-serverless-forwarder).
• build_pr.sh consults the helper inside the product-repo path (before cloning) and exits 0 when the target branch isn't in the repo's legacy set. Fails open on any helper error or unknown repo, so a real build is never blocked.
• Deriving from conf.yaml means the guard needs no edits as products migrate — no hardcoded version patterns.

Test plan

Verified the helper locally (Perl YAML present):

• legacy_branches.pl elasticsearch → 8.19 … 0.90, no 9.x
• legacy_branches.pl cloud → ms-* milestones (+ master), no main
• legacy_branches.pl cloud-on-k8s → 0.8 … 2.16, no 3.x
• legacy_branches.pl elastic-serverless-forwarder → resolves via esf key
• legacy_branches.pl clients-team → main (proves map_branches)
• unknown repo → exit 2 (fail open)
• shellcheck .buildkite/scripts/build_pr.sh clean for the new guard

Behavioral: elasticsearch+main → skip 0; +8.18 → build. cloud+main → skip 0; +ms-119 → build. cloud-on-k8s+3.0 → skip 0; +2.16 → build.

Notes

The guard runs on the host agent (docs-ubuntu-2204). libyaml-perl is installed in the build Dockerfile (inside the container) but the host image's Perl YAML status is unconfirmed. The fail-open behavior means no regression if it's missing — the skip simply won't take effect until libyaml-perl is added to the agent image (verify with perl -MYAML -e1).

🤖 Generated with Claude Code

[github-actions]

A documentation preview will be available soon.

• 🔨 Buildkite builds
• 📚 HTML diff
• 📙 Preview page

Request a new doc build by commenting

• Rebuild this PR: run docs-build
• Rebuild this PR and all Elastic docs: run docs-build rebuild

_{run docs-build is much faster than run docs-build rebuild. A rebuild should only be needed in rare situations.}

_{If your PR continues to fail for an unknown reason, the doc build pipeline may be broken. Elastic employees can check the pipeline status here.}

[Mpdreamz]

This is great and love the pl checking conf.yml

I think we can hardcore main and master as fallback even if the yaml dep is missing?

[reakaleek]

Fixed in 2c5891e — added a pre-check that hardcodes main/master to always build, bypassing legacy_branches.pl (and its YAML dependency) entirely for those branches. Went this direction rather than a post-failure fallback since conf.yaml shows many repos still carry legacy docs on their default branch via the do-not-delete_legacy-docs pattern, so it's the one case worth never trusting to the parse.

[reakaleek]

Correction to my earlier comment: main/master should always skip the build, not always build — we no longer build legacy AsciiDoc docs against those branches. Fixed in 7368322 (amended over the previous, incorrect commit): a pre-check now exits 0 for main/master before touching legacy_branches.pl/conf.yaml at all.

[reakaleek]

Further correction, sorry for the churn: the real goal is build only when conf.yaml has a matching legacy branch, not fail-open. Fixed in 2b8c084 (amended again):

• main/master still hardcode to always skip (unrelated to YAML/conf.yaml — they simply no longer carry AsciiDoc docs).
• For every other branch, flipped from fail-open to positive-match: build only if conf.yaml lists the branch as legacy for that repo. A migrated or unknown repo (empty/missing list) now skips instead of building.
• Genuine parse failures (e.g. missing YAML module) still fail open and build, since we can't tell in that case — this preserves your original concern about never silently going green when the tooling itself is broken.

Verified legacy_branches.pl's branch-resolution rules against lib/ES/Book.pm/lib/ES/Source.pm (the real build code) line by line — they match exactly, so no drift risk there.

[reakaleek]

Ran a /simplify pass (reuse, simplification, efficiency, altitude) and it surfaced a real bug in legacy_branches.pl's own new code, now fixed in 5d1b163eddb718d5a3bfc5ff95fa00543c7ba4d4 (amended):

legacy_branches.pl translated the GitHub repo name to its conf.yaml key by stripping the source URL to a basename (e.g. elastic-serverless-forwarder → esf). But some repos (esf, kibana-cn, swiftype) are passed in as the conf key itself, which that basename-only lookup never matched — so it silently returned "no legacy branches" and would have always skipped their builds regardless of target branch. Fixed by trying a direct key match first, falling back to the basename translation. Added legacy_branches.t as a regression check for both paths.

The other 3 review angles (reuse, simplification, efficiency) came back clean — no changes needed there.