ci: skip Go jobs and add docs-site build for docs-only PRs by bloxster · Pull Request #21028 · erigontech/erigon

bloxster · 2026-05-07T07:27:19Z

Summary

Add a changes job that queries the GitHub API to detect whether any non-docs files changed in the PR.
Skip Go CI jobs (tests, race-tests, eest-spec-tests, lint, bench, kurtosis, repro, sonar, caplin, hive) when every changed file is docs-only.
Add a docs-site job that runs whenever docs/site/** is touched. It runs four steps:
- npm ci → typecheck → docusaurus build (with onBrokenLinks / onBrokenMarkdownLinks / onBrokenAnchors all set to throw, so internal broken links fail at PR time)
- python3 docs/site/scripts/generate-llms.py --check — drift check that the committed llms.txt / llms-full.txt match what the generator produces (mirrors the guard in [r3.4] docs: add llms.txt generator script and update root llms.txt #21000's docs-deploy.yml so PRs to main get the same protection that release/3.4 gets at deploy time)
- python3 -m unittest discover docs/site/scripts -v — 25-test suite for the generator
Keep the full suite for merge_group and workflow_dispatch.
Include changes and docs-site in ci-gate needs; if the GitHub API call in changes fails, the step exits non-zero instead of silently skipping jobs (which would have defaulted to code=true, but better to fail loud than absorb errors).
Add pull-requests: read permission so the gh api pulls/N/files call works without a 403.
Run lint for all event types, including merge_group (was previously PR-only).

docs-site-build.yml guard behavior

Silent skip only when docs/site/ directory is entirely absent (e.g. backports to branches that predate the Docusaurus migration).
Fail loud when the directory exists but a specific prerequisite is missing (package.json, package-lock.json, scripts/, scripts/generate-llms.py) — these would indicate a partially-broken docs setup that should not pass CI silently.

CI matrix after this merges

PR type	`large-files`	`docs-site`	Go CI
`docs/site/**` only	yes	build + typecheck + llms drift + unittests	skipped
`docs/site/**` + code	yes	build + typecheck + llms drift + unittests	full suite
docs-only outside `docs/site/` (root `.md`, `llms.txt`)	yes	skipped	skipped
code only	yes	skipped	full suite
workflow / non-docs changes	yes	skipped unless `docs/site/**` touched	full suite
`merge_group`	n/a	build + typecheck + llms drift + unittests	full suite

large-files is intentionally not gated on code — it's cheap and remains useful for docs-only PRs.

File-pattern logic

A PR is considered docs-only, and skips Go CI, when every changed file matches:

^(docs/|llms[^/]*\.txt$|[^/]*\.md$)

That means files under docs/, root-level llms*.txt (e.g. llms.txt, llms-full.txt — regenerated by generate-llms.py on every docs build), or root-level *.md (README.md, CLAUDE.md, etc.). Nested Markdown outside docs/, such as execution/README.md, still counts as a code change.

Validation

This PR changes .github/workflows/, so it is intentionally not docs-only and the full CI suite runs.
The changes job completed successfully on this PR.
ci-gate completed successfully on the latest pushed commit.

🤖 Generated with Claude Code

Add a `changes` job that detects whether any non-docs files changed. Go CI jobs (tests, race-tests, lint, bench, kurtosis, repro, sonar, caplin, hive) are skipped when every changed file is under docs/, saving ~30 min of unnecessary CI for docs-only PRs. Add `docs-site` job (npm ci → typecheck → docusaurus build) that runs whenever docs/site/** is touched. Docusaurus is configured with onBrokenLinks/onBrokenMarkdownLinks/onBrokenAnchors all set to 'throw', so the build catches internal broken links at PR time. For merge_group and workflow_dispatch the full suite always runs. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

This PR updates the CI gate workflow to detect docs-only pull requests and skip expensive Go CI jobs when only docs/** files changed, while adding a dedicated docs-site build (typecheck + Docusaurus build) when docs/site/** is touched.

Changes:

Add a changes job to classify PRs as “code changed” vs “docs-only”, and conditionally skip Go CI jobs for docs-only PRs.
Add a reusable docs-site-build.yml workflow and a docs-site job in ci-gate to run npm ci → typecheck → build when docs/site/** changes.
Wire changes outputs into job if: conditions and include changes/docs-site in the ci-gate aggregation.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
.github/workflows/docs-site-build.yml	Adds a reusable workflow to typecheck and build the Docusaurus docs site.
.github/workflows/ci-gate.yml	Adds PR-change detection and uses it to skip Go CI for docs-only PRs; triggers docs-site build when needed.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

- Add pull-requests:read permission so the gh api call in the changes job can fetch PR file lists without a 403 - Remove the pull_request guard on lint so it also runs in merge_group Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

llms.txt and llms-full.txt live at the repo root and are regenerated by the Docusaurus build (docs/site/scripts/generate-llms.py). Without this, PRs that update those files would trigger the full Go CI suite despite being pure docs changes. Also extends the pattern to root-level *.md files (README.md, CLAUDE.md, etc.) for the same reason. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/site/ does not exist on main until PR #21013 merges. Without a guard, the docs-site job fires for merge_group events (docs_site=true for all non-PR events) and fails on npm ci in a missing directory, blocking this PR from merging itself. Add a presence check on docs/site/package.json; steps are skipped (job passes) when the directory is absent. Also: - node-version '20' -> '20.x' (standard semver range notation) - drop secrets:inherit from docs-site job (build needs no secrets) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

bloxster · 2026-05-07T08:02:54Z

Additional fix pushed (llms.txt coverage):

After reviewing #21000, noticed that llms.txt and llms-full.txt live at the repo root (not under docs/), and are regenerated by the Docusaurus build script on every docs update. Without a fix, any PR touching those files would have triggered the full Go CI suite despite being a pure docs change.

Extended the changes job filter pattern from '^docs/' to:
```
'^(docs/|llms[^/].txt$|[^/].md$)'
```

This excludes from the "code changed" check:

llms[^/]*\.txt$ — root-level llms.txt, llms-full.txt (and any future variants)
[^/]*\.md$ — root-level *.md files (README.md, CLAUDE.md, etc.)

Nested .md files inside Go packages (e.g. execution/README.md) are still treated as code changes — intentional.

- Fail explicitly if gh api call returns an error instead of silently continuing with empty $files (which would default to code=true) - Add comment explaining the file-pattern regex for future maintainers

When a PR touches docs/site/**, also verify: - generate-llms.py --check (regenerated outputs match committed files) - unittest discover (25-test suite stays green) Mirrors the guard in #21000's docs-deploy.yml so PRs to main get the same llms.txt drift protection that release/3.4 gets at deploy time.

## Summary Sibling of #21028 (which lands the same path-filter on `main`'s `ci-gate.yml`). When a PR only touches `docs/`, root `llms*.txt`, or root `*.md`, skip the `linux` and `win` Go test runs (~20-30 min saved per PR) and instead run a docs-site typecheck/build with the llms.txt drift + unittest guard. ### How it works A new fast `changes` job calls `gh api .../pulls/{n}/files` and emits two outputs: - `code` — `false` if every changed file is under `docs/`, root `llms*.txt`, or root `*.md`; otherwise `true`. Defaults to `true` for `push` / `workflow_dispatch` so nothing is skipped on merge. - `docs_site` — `true` when any `docs/site/**` file is touched. `linux` and `win` are gated on `code != 'false'`. A new `docs-site` job (calling the new reusable `docs-site-build.yml`) runs when `docs_site == 'true'`. If the `gh api` call fails, the step exits with code 1 — the gate fails rather than silently defaulting to skipping jobs. ### What runs when | PR scope | linux/win | docs-site | |----------|-----------|-----------| | Pure code (`*.go`, etc.) | ✅ runs | ⏭️ skipped | | Mixed code + docs | ✅ runs | ✅ runs | | Pure docs (`docs/site/**`) | ⏭️ skipped | ✅ runs | | Pure root-level docs (`llms.txt`, `README.md`) | ⏭️ skipped | ⏭️ skipped | | `push` to `main` / `release/**` | ✅ runs | ✅ runs | ### File-pattern logic A PR is **docs-only** (skips Go CI) when every changed file matches: ``` ^(docs/|llms[^/]*\.txt$|[^/]*\.md$) ``` i.e. files under `docs/`, root-level `llms*.txt`, or root-level `*.md`. Nested `.md` files (e.g. `execution/README.md`) still count as code changes. ### `docs-site-build.yml` Reusable `workflow_call` leaf that: 1. Sets up Python 3.11 + runs `python3 docs/site/scripts/generate-llms.py --check` and `python3 -m unittest discover docs/site/scripts -v` (the llms drift guard from #21000) 2. Sets up Node 20 + runs `npm ci`, `npm run typecheck`, `npm run build` against `docs/site/` Has a defensive guard that skips silently if `docs/site/package.json` **or** `docs/site/scripts/generate-llms.py` is absent — covering both fully absent `docs/site/` and partial migration states. ### Files | File | Change | |------|--------| | `.github/workflows/ci.yml` | Add `permissions: pull-requests: read`, `changes` job, gate `linux`/`win` with `code != 'false'`, add `docs-site` job | | `.github/workflows/docs-site-build.yml` | New reusable workflow (Python llms guard + Node typecheck/build) | ## Test plan - [ ] Open a docs-only PR (touch `docs/site/docs/...`) — confirm `linux`/`win` are skipped and `docs-site` runs - [ ] Open a mixed PR (one `.go` file + one `.md` file) — confirm both `linux`/`win` and `docs-site` run - [ ] Open a pure code PR — confirm `docs-site` is skipped, `linux`/`win` run - [ ] Push to `release/3.4` — confirm everything runs (no skipping) 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Bloxster <bloxster@proton.me> Co-authored-by: Gianni <gianni@erigon.dev> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

bloxster · 2026-05-13T13:21:13Z

@copilot apply changes based on the comments in this thread

Agent-Logs-Url: https://github.com/erigontech/erigon/sessions/72fb002f-851c-4b56-82dd-b85f795002bc Co-authored-by: bloxster <40316187+bloxster@users.noreply.github.com>

Copilot · 2026-05-13T13:38:57Z

@copilot apply changes based on the comments in this thread

Applied in 9a05646: eest-spec-tests is now gated with needs: [changes] + if: needs.changes.outputs.code != 'false', and docs-site-build.yml now only skips when docs/site/ is absent while failing if required prerequisites are missing.

bloxster · 2026-05-13T15:53:06Z

@copilot apply changes based on the comments in this thread

Copilot · 2026-05-13T15:54:58Z

@copilot apply changes based on the comments in this thread

Applied in 9a05646 — both items from that review thread are in place (eest-spec-tests docs-only gating in ci-gate.yml, and strict docs-site prerequisite validation in docs-site-build.yml).

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

yperbasis

LGTM. Nice job on the docs-only fast path and on addressing the prior review comments (pull-requests:read, eest-spec-tests gating, docs-site prereq validation).

A few non-blocking nits:

needs.changes.outputs.code != 'false' vs == 'true' — functionally equivalent here, but == 'true' reads more directly. Style only.
The docs-site silent-skip path (present=false) is essentially dead code on main: the job only triggers when docs_site=true, which requires ^docs/site/ in the PR file list, which requires the directory to exist at HEAD. It's only useful on backports to legacy branches that predate the Docusaurus migration. Worth a one-line comment clarifying that, or just leaving as-is.
The PR summary lists npm ci → typecheck → docusaurus build, but docs-site-build.yml also runs generate-llms.py --check and python3 -m unittest discover docs/site/scripts. The drift check is valuable — but worth surfacing in the description so reviewers aren't surprised that a docs-only PR now also exercises the Python tooling.
large-files isn't gated on code — docs-only PRs still pay for it. Cheap job, fine to leave, but for consistency you could add the same needs.changes.outputs.code != 'false' guard.

Worth watching after merge:

First docs-only PR that lands: confirm Go jobs show as skipped and ci-gate still passes.
First merge_group run: confirm lint now actually runs (was previously PR-only).
First fork-PR docs-only change: confirm pull-requests: read is sufficient for the gh api pulls/N/files call from a forked head — that's the most likely surprise.

…21277) ## Summary Pure mechanical regeneration of `llms-full.txt` (both root and `docs/site/static/` copies) via `python3 docs/site/scripts/generate-llms.py`. Catches up accumulated drift from prior docs PRs that landed before #21028 added the `--check` step to `ci-gate`. ## Drift content - **New flags documented**: `--erigondb.domain.steps-in-frozen-file`, `--caplin.nat`, `--caplin.columns-keep-slots` - **Corrected defaults**: `--log.dir.verbosity` (added missing default), `--rpc.subscription.filters.maxlogs/maxheaders/maxtxs` (`0` → `10000`) - **Smart-quote normalization** in two CLI flag descriptions - **New "Caplin (consensus layer) NAT" doc section** pulled in from `docs/site/docs/` ## Why now #21028 is stuck in the merge queue because its `docs-site` job now runs `generate-llms.py --check` against every `merge_group` event. That check correctly catches the pre-existing drift on main and fails the queue's CI Gate. Landing this PR clears the drift so #21028's next requeue passes. ## Test plan - [x] `python3 docs/site/scripts/generate-llms.py --check` → "OK: 4 llms files match regenerated content" - [x] Diff is pure regeneration (no manual edits) - [ ] After merge, requeue #21028 → expect docs-site / build to pass 🤖 Generated with Claude Code --------- Co-authored-by: Bloxster <bloxster@proton.me> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The action's OIDC token exchange requires write access; fork PRs fail with 'User does not have write access on this repository'. Gate on head.repo.full_name == github.repository to skip cleanly on forks.

The claude-code-action validates that the workflow file on the PR branch is identical to the version on main — a security safeguard against PRs disabling their own code review. The previous commit caused that check to hard-fail. If a fork guard is still wanted it must land on main first via a separate PR.

bloxster requested review from AskAlexSharov and mriccobene as code owners May 7, 2026 07:27

bloxster requested a review from Copilot May 7, 2026 07:28

Copilot started reviewing on behalf of bloxster May 7, 2026 07:28 View session

bloxster added the docs label May 7, 2026

Copilot AI reviewed May 7, 2026

View reviewed changes

Comment thread .github/workflows/ci-gate.yml

Comment thread .github/workflows/ci-gate.yml

bloxster and others added 3 commits May 7, 2026 09:48

bloxster and others added 5 commits May 7, 2026 10:44

Merge branch 'main' into ci/docs-path-filter

4346d5e

ci: add error handling and comment to changes job

127f917

- Fail explicitly if gh api call returns an error instead of silently continuing with empty $files (which would default to code=true) - Add comment explaining the file-pattern regex for future maintainers

Merge branch 'main' into ci/docs-path-filter

8f993b7

Merge branch 'main' into ci/docs-path-filter

abbe215

bloxster mentioned this pull request May 7, 2026

ci: skip Go jobs and add docs-site build for docs-only PRs #21045

Merged

4 tasks

bloxster and others added 4 commits May 9, 2026 11:44

ci: align docs-site-build.yml guard with r3.4 version

8b1bcd2

Merge branch 'main' into ci/docs-path-filter

4b5c738

Merge branch 'main' into ci/docs-path-filter

c7b2a22

Merge branch 'main' into ci/docs-path-filter

e55a77e

bloxster requested a review from yperbasis May 13, 2026 11:44

yperbasis requested a review from Copilot May 13, 2026 11:49

yperbasis added the QA label May 13, 2026

Copilot started reviewing on behalf of yperbasis May 13, 2026 11:50 View session

Copilot AI reviewed May 13, 2026

View reviewed changes

Comment thread .github/workflows/ci-gate.yml

Comment thread .github/workflows/docs-site-build.yml Outdated

Copilot started work on behalf of bloxster May 13, 2026 13:21 View session

ci: gate eest-spec-tests and tighten docs-site prerequisites

9a05646

Agent-Logs-Url: https://github.com/erigontech/erigon/sessions/72fb002f-851c-4b56-82dd-b85f795002bc Co-authored-by: bloxster <40316187+bloxster@users.noreply.github.com>

Copilot finished work on behalf of bloxster May 13, 2026 13:40

Copilot started work on behalf of bloxster May 13, 2026 15:53 View session

Copilot finished work on behalf of bloxster May 13, 2026 15:55

yperbasis requested a review from Copilot May 19, 2026 10:56

Copilot started reviewing on behalf of yperbasis May 19, 2026 10:56 View session

Copilot AI reviewed May 19, 2026

View reviewed changes

yperbasis approved these changes May 19, 2026

View reviewed changes

bloxster added this pull request to the merge queue May 19, 2026

github-merge-queue Bot removed this pull request from the merge queue due to failed status checks May 19, 2026

bloxster mentioned this pull request May 19, 2026

docs: regenerate llms-full.txt to match current docs/site/ content #21277

Merged

3 tasks

bloxster added 2 commits May 20, 2026 08:57

ci: skip claude-review on fork PRs

5800d4b

The action's OIDC token exchange requires write access; fork PRs fail with 'User does not have write access on this repository'. Gate on head.repo.full_name == github.repository to skip cleanly on forks.

Merge remote-tracking branch 'origin/main' into ci/docs-path-filter

b5cc2ae

bloxster requested a review from lystopad as a code owner May 20, 2026 06:58

lystopad approved these changes May 20, 2026

View reviewed changes

bloxster enabled auto-merge May 20, 2026 07:53

bloxster added this pull request to the merge queue May 20, 2026

Merged via the queue into main with commit 4ccd6f6 May 20, 2026
132 of 134 checks passed

bloxster deleted the ci/docs-path-filter branch May 20, 2026 09:09

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ci: skip Go jobs and add docs-site build for docs-only PRs#21028

ci: skip Go jobs and add docs-site build for docs-only PRs#21028
bloxster merged 17 commits into
mainfrom
ci/docs-path-filter

bloxster commented May 7, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

bloxster commented May 7, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

bloxster commented May 13, 2026

Uh oh!

Copilot AI commented May 13, 2026

Uh oh!

bloxster commented May 13, 2026

Uh oh!

Copilot AI commented May 13, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

yperbasis left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Conversation

bloxster commented May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

docs-site-build.yml guard behavior

CI matrix after this merges

File-pattern logic

Validation

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

bloxster commented May 7, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

bloxster commented May 13, 2026

Uh oh!

Copilot AI commented May 13, 2026

Uh oh!

bloxster commented May 13, 2026

Uh oh!

Copilot AI commented May 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

yperbasis left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

bloxster commented May 7, 2026 •

edited

Loading