From f1159820adac395f4b71dd5774373c1992a1d1b8 Mon Sep 17 00:00:00 2001 From: danceratopz Date: Thu, 9 Apr 2026 09:43:54 +0200 Subject: [PATCH 01/27] feat(docs): add `docs-build` workflow for parallel doc generation Split HTML docs (`mkdocs`) and spec docs (`docc`) into parallel CI jobs that produce a combined artifact for `steel-website` deployment. - Add `docs-build.yaml` with five jobs: `check-should-publish`, `html-docs`, `spec-docs`, `combine`, and `trigger-aggregator`. - Add `.github/configs/docs-branches.yaml` branch allowlist. - Slim `test-docs.yaml` to changelog and markdown lint only (renamed to "Static Doc Checks"); the `mkdocs` build job moves to the new workflow. - Update `mkdocs.yml` `site_url` to read from `SITE_URL` env var with fallback to `steel.ethereum.foundation/docs/`. - Update `DocsConfig` URLs to `steel.ethereum.foundation/docs`. --- .github/configs/docs-branches.yaml | 14 + .github/workflows/docs-build.yaml | 281 ++++++++++++++++++ .github/workflows/test-docs.yaml | 18 +- mkdocs.yml | 4 +- .../src/execution_testing/config/docs.py | 4 +- 5 files changed, 302 insertions(+), 19 deletions(-) create mode 100644 .github/configs/docs-branches.yaml create mode 100644 .github/workflows/docs-build.yaml diff --git a/.github/configs/docs-branches.yaml b/.github/configs/docs-branches.yaml new file mode 100644 index 00000000000..98843e83a57 --- /dev/null +++ b/.github/configs/docs-branches.yaml @@ -0,0 +1,14 @@ +# Branches whose documentation is built and published to +# steel.ethereum.foundation/docs/ +# +# Must stay in sync with steel-website's BRANCH_CONFIG in deploy.yml. +# +# Each entry defines: +# - path: The branch name (must match the Git branch exactly) +# - label: Human-readable label for the version switcher UI + +default: "forks/amsterdam" + +branches: + - path: "forks/amsterdam" + label: "Amsterdam" diff --git a/.github/workflows/docs-build.yaml b/.github/workflows/docs-build.yaml new file mode 100644 index 00000000000..7aaea573779 --- /dev/null +++ b/.github/workflows/docs-build.yaml @@ -0,0 +1,281 @@ +# Build Docs +# +# Dual-purpose workflow: +# - On PRs: Tests that MkDocs and spec docs build successfully +# - On push to allowlisted branches: Builds, uploads artifacts, and triggers +# the aggregator workflow in steel-website for deployment +# +# Site structure at steel.ethereum.foundation/docs/: +# /docs/ - Default branch docs (mirrored) +# /docs/spec/ - Default branch spec (mirrored) +# /docs// - Branch-specific docs +# /docs//spec - Branch-specific spec + +name: Build Docs + +on: + push: + branches: + - mainnet + - "forks/**" + - "devnets/**" + - "eips/**" + - "projects/**" + paths: &docs_paths + - "src/ethereum/**" + - "src/ethereum_spec_tools/docc.py" + - "src/ethereum_spec_tools/forks.py" + - "static/**" + - "docs/**" + - "packages/testing/**" + - "CONTRIBUTING.md" + - "SECURITY.md" + - "mkdocs.yml" + - "uv.lock" + - "pyproject.toml" + - ".github/workflows/docs-build.yaml" + - ".github/configs/docs-branches.yaml" + + pull_request: + paths: *docs_paths + + workflow_dispatch: + inputs: + branch: + description: "Branch to build (must be allowlisted)" + required: false + type: string + +concurrency: + group: docs-build-${{ github.ref }} + cancel-in-progress: true + +permissions: + contents: read + +jobs: + check-should-publish: + name: "Check Should Publish" + runs-on: ubuntu-latest + outputs: + should_publish: ${{ steps.check.outputs.should_publish }} + branch: ${{ steps.check.outputs.branch }} + branch_artifact_name: ${{ steps.check.outputs.branch_artifact_name }} + is_deploy: ${{ steps.check.outputs.is_deploy }} + steps: + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + sparse-checkout: .github/configs/docs-branches.yaml + sparse-checkout-cone-mode: false + + - name: Resolve publish configuration + id: check + env: + BRANCH_INPUT: ${{ github.event.inputs.branch || github.ref_name }} + EVENT_NAME: ${{ github.event_name }} + run: | + echo "branch=$BRANCH_INPUT" >> "$GITHUB_OUTPUT" + + # Create artifact-safe name (replace / with -) + BRANCH_ARTIFACT_NAME="${BRANCH_INPUT//\//-}" + echo "branch_artifact_name=$BRANCH_ARTIFACT_NAME" >> "$GITHUB_OUTPUT" + + # Deploy on push and workflow_dispatch, not on PRs + IS_DEPLOY="false" + if [ "$EVENT_NAME" = "push" ] || [ "$EVENT_NAME" = "workflow_dispatch" ]; then + IS_DEPLOY="true" + fi + echo "is_deploy=$IS_DEPLOY" >> "$GITHUB_OUTPUT" + + # Extract branch paths from allowlist config + ALLOWLISTED_BRANCHES=$(yq '.branches[].path' .github/configs/docs-branches.yaml 2>/dev/null || echo "") + + if [ -z "$ALLOWLISTED_BRANCHES" ]; then + echo "ERROR: Could not read allowlist from .github/configs/docs-branches.yaml" + echo "should_publish=false" >> "$GITHUB_OUTPUT" + exit 0 + fi + + # Check if branch is in allowlist + if echo "$ALLOWLISTED_BRANCHES" | grep -qxF "$BRANCH_INPUT"; then + echo "should_publish=true" >> "$GITHUB_OUTPUT" + echo "Branch '$BRANCH_INPUT' is allowlisted for publishing" + else + echo "should_publish=false" >> "$GITHUB_OUTPUT" + echo "Branch '$BRANCH_INPUT' is not allowlisted for publishing" + echo "Allowlisted branches:" + echo "$ALLOWLISTED_BRANCHES" | sed 's/^/ - /' + fi + + html-docs: + name: "Build HTML Docs" + runs-on: ubuntu-latest + needs: check-should-publish + # Always build for PRs (testing); only build for push if allowlisted + if: github.event_name == 'pull_request' || needs.check-should-publish.outputs.should_publish == 'true' + + steps: + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + ref: ${{ github.event_name == 'workflow_dispatch' && needs.check-should-publish.outputs.branch || '' }} + fetch-depth: 0 + submodules: recursive + + - uses: ./.github/actions/setup-uv + + - name: Build MkDocs documentation + env: + BRANCH: ${{ needs.check-should-publish.outputs.branch }} + IS_DEPLOY: ${{ needs.check-should-publish.outputs.is_deploy }} + run: | + if [ "$IS_DEPLOY" = "true" ]; then + export SITE_URL="https://steel.ethereum.foundation/docs/${BRANCH}/" + else + export SITE_URL="https://example.com/docs/${BRANCH}/" + fi + + echo "Building MkDocs with SITE_URL=$SITE_URL" + just docs + + - name: Upload HTML docs artifact + if: needs.check-should-publish.outputs.is_deploy == 'true' + uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0 + with: + name: docs-html-${{ needs.check-should-publish.outputs.branch_artifact_name }} + path: .just/docs/site/ + retention-days: 1 + if-no-files-found: error + + spec-docs: + name: "Build Spec Docs" + runs-on: ubuntu-latest + needs: check-should-publish + if: github.event_name == 'pull_request' || needs.check-should-publish.outputs.should_publish == 'true' + + steps: + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + ref: ${{ github.event_name == 'workflow_dispatch' && needs.check-should-publish.outputs.branch || '' }} + fetch-depth: 0 + submodules: recursive + + - uses: ./.github/actions/setup-uv + + - name: Build spec documentation + run: just docs-spec + env: + DOCC_SKIP_DIFFS: ${{ case(github.event_name == 'push' && github.ref_name == github.event.repository.default_branch, '', '1') }} + + - name: Upload spec docs artifact + if: needs.check-should-publish.outputs.is_deploy == 'true' + uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0 + with: + name: docs-spec-${{ needs.check-should-publish.outputs.branch_artifact_name }} + path: .just/docs-spec/ + retention-days: 1 + if-no-files-found: error + + combine: + name: "Combine and Upload" + runs-on: ubuntu-latest + needs: [check-should-publish, html-docs, spec-docs] + if: needs.check-should-publish.outputs.is_deploy == 'true' && needs.check-should-publish.outputs.should_publish == 'true' + + steps: + - name: Download HTML docs artifact + uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0 + with: + name: docs-html-${{ needs.check-should-publish.outputs.branch_artifact_name }} + path: html-docs/ + + - name: Download spec docs artifact + uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0 + with: + name: docs-spec-${{ needs.check-should-publish.outputs.branch_artifact_name }} + path: spec-docs/ + + - name: Stage combined artifact + env: + BRANCH: ${{ needs.check-should-publish.outputs.branch }} + run: | + mkdir -p "stage/${BRANCH}/spec" + + # HTML docs at root of branch directory + rsync -a html-docs/ "stage/${BRANCH}/" + + # Spec docs in spec/ subdirectory + rsync -a spec-docs/ "stage/${BRANCH}/spec/" + + # Build metadata + cat > "stage/${BRANCH}/metadata.json" < Date: Thu, 9 Apr 2026 09:44:39 +0200 Subject: [PATCH 02/27] test(docs): temporarily widen workflow for E2E testing Add `experiments/**` branch trigger and `experiments/publish-docs` to the allowlist so the full pipeline (including `combine` and `trigger-aggregator`) runs on push. Revert before merge. --- .github/configs/docs-branches.yaml | 3 +++ .github/workflows/docs-build.yaml | 1 + 2 files changed, 4 insertions(+) diff --git a/.github/configs/docs-branches.yaml b/.github/configs/docs-branches.yaml index 98843e83a57..95d26923140 100644 --- a/.github/configs/docs-branches.yaml +++ b/.github/configs/docs-branches.yaml @@ -12,3 +12,6 @@ default: "forks/amsterdam" branches: - path: "forks/amsterdam" label: "Amsterdam" + # TEMPORARY: remove after E2E testing + - path: "experiments/publish-docs" + label: "Amsterdam" diff --git a/.github/workflows/docs-build.yaml b/.github/workflows/docs-build.yaml index 7aaea573779..5a385239985 100644 --- a/.github/workflows/docs-build.yaml +++ b/.github/workflows/docs-build.yaml @@ -21,6 +21,7 @@ on: - "devnets/**" - "eips/**" - "projects/**" + - "experiments/**" # TEMPORARY: remove after E2E testing paths: &docs_paths - "src/ethereum/**" - "src/ethereum_spec_tools/docc.py" From 53926050ab9004eab1c78ff2d31cc683ebcf275d Mon Sep 17 00:00:00 2001 From: danceratopz Date: Thu, 9 Apr 2026 10:03:23 +0200 Subject: [PATCH 03/27] feat(ci): add job summary to `check-should-publish` Write a summary table with branch, event, deploy, and allowlist status. Include a callout explaining why artifacts will or will not be published. --- .github/workflows/docs-build.yaml | 35 +++++++++++++++++++++++++------ 1 file changed, 29 insertions(+), 6 deletions(-) diff --git a/.github/workflows/docs-build.yaml b/.github/workflows/docs-build.yaml index 5a385239985..689bd5ee3b0 100644 --- a/.github/workflows/docs-build.yaml +++ b/.github/workflows/docs-build.yaml @@ -99,14 +99,37 @@ jobs: # Check if branch is in allowlist if echo "$ALLOWLISTED_BRANCHES" | grep -qxF "$BRANCH_INPUT"; then - echo "should_publish=true" >> "$GITHUB_OUTPUT" - echo "Branch '$BRANCH_INPUT' is allowlisted for publishing" + SHOULD_PUBLISH="true" else - echo "should_publish=false" >> "$GITHUB_OUTPUT" - echo "Branch '$BRANCH_INPUT' is not allowlisted for publishing" - echo "Allowlisted branches:" - echo "$ALLOWLISTED_BRANCHES" | sed 's/^/ - /' + SHOULD_PUBLISH="false" fi + echo "should_publish=$SHOULD_PUBLISH" >> "$GITHUB_OUTPUT" + + # Write job summary + { + echo "## Check Should Publish" + echo "" + echo "| Setting | Value |" + echo "|---------|-------|" + echo "| **Branch** | \`$BRANCH_INPUT\` |" + echo "| **Event** | \`$EVENT_NAME\` |" + echo "| **Deploy build** | $IS_DEPLOY |" + echo "| **Allowlisted** | $SHOULD_PUBLISH |" + echo "" + + if [ "$EVENT_NAME" = "pull_request" ]; then + echo "-> **Build only** -- pull request; artifacts are not published." + elif [ "$SHOULD_PUBLISH" = "true" ]; then + echo "-> **Will publish** -- branch is allowlisted; artifacts will be built, combined, and uploaded." + else + echo "-> **Skipping publish** -- branch is not in the allowlist (\`.github/configs/docs-branches.yaml\`)." + echo "" + echo "Allowlisted branches:" + echo "$ALLOWLISTED_BRANCHES" | while read -r b; do + echo "- \`$b\`" + done + fi + } >> "$GITHUB_STEP_SUMMARY" html-docs: name: "Build HTML Docs" From b75c8460c863b53d47514a37850a0c95e50f9200 Mon Sep 17 00:00:00 2001 From: danceratopz Date: Thu, 9 Apr 2026 10:50:49 +0200 Subject: [PATCH 04/27] chore: trigger CI From 22921384e7f7b122880ddcc273563b3d41e7427a Mon Sep 17 00:00:00 2001 From: danceratopz Date: Thu, 9 Apr 2026 12:45:19 +0200 Subject: [PATCH 05/27] test(docs): add second test branch to allowlist for version selector testing --- .github/configs/docs-branches.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/configs/docs-branches.yaml b/.github/configs/docs-branches.yaml index 95d26923140..0b726734fb8 100644 --- a/.github/configs/docs-branches.yaml +++ b/.github/configs/docs-branches.yaml @@ -15,3 +15,5 @@ branches: # TEMPORARY: remove after E2E testing - path: "experiments/publish-docs" label: "Amsterdam" + - path: "experiments/publish-docs-test" + label: "Amsterdam (Test)" From 42e4e904c71a6b5318568a032b575070c40f1239 Mon Sep 17 00:00:00 2001 From: danceratopz Date: Wed, 15 Apr 2026 14:35:44 +0200 Subject: [PATCH 06/27] chore(ci): remove test config; ready for merge Intentionally not dropping original commits for transparency. --- .github/configs/docs-branches.yaml | 5 ----- .github/workflows/docs-build.yaml | 1 - 2 files changed, 6 deletions(-) diff --git a/.github/configs/docs-branches.yaml b/.github/configs/docs-branches.yaml index 0b726734fb8..98843e83a57 100644 --- a/.github/configs/docs-branches.yaml +++ b/.github/configs/docs-branches.yaml @@ -12,8 +12,3 @@ default: "forks/amsterdam" branches: - path: "forks/amsterdam" label: "Amsterdam" - # TEMPORARY: remove after E2E testing - - path: "experiments/publish-docs" - label: "Amsterdam" - - path: "experiments/publish-docs-test" - label: "Amsterdam (Test)" diff --git a/.github/workflows/docs-build.yaml b/.github/workflows/docs-build.yaml index 689bd5ee3b0..8b09012882e 100644 --- a/.github/workflows/docs-build.yaml +++ b/.github/workflows/docs-build.yaml @@ -21,7 +21,6 @@ on: - "devnets/**" - "eips/**" - "projects/**" - - "experiments/**" # TEMPORARY: remove after E2E testing paths: &docs_paths - "src/ethereum/**" - "src/ethereum_spec_tools/docc.py" From da9c9b34ea3660a1ce5ae365636a2c55144343f1 Mon Sep 17 00:00:00 2001 From: danceratopz Date: Wed, 15 Apr 2026 14:54:14 +0200 Subject: [PATCH 07/27] fix(ci): use target branch tip SHA in docs metadata and dispatch For `workflow_dispatch`, `github.sha` points at the launch ref (typically the default branch), not at the branch that `html-docs`/`spec-docs` actually check out via the `ref:` override. Published `metadata.json` and the `steel-website` dispatch payload therefore could reference a commit on a different branch than the one that was built. Resolve the tip SHA of the target branch in `check-should-publish` via `git ls-remote` and expose it as a job output. Consume that output in the `combine` metadata step and the `trigger-aggregator` dispatch. --- .github/workflows/docs-build.yaml | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs-build.yaml b/.github/workflows/docs-build.yaml index 8b09012882e..bd34e6f0d32 100644 --- a/.github/workflows/docs-build.yaml +++ b/.github/workflows/docs-build.yaml @@ -62,6 +62,7 @@ jobs: branch: ${{ steps.check.outputs.branch }} branch_artifact_name: ${{ steps.check.outputs.branch_artifact_name }} is_deploy: ${{ steps.check.outputs.is_deploy }} + commit_sha: ${{ steps.check.outputs.commit_sha }} steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 with: @@ -104,6 +105,22 @@ jobs: fi echo "should_publish=$SHOULD_PUBLISH" >> "$GITHUB_OUTPUT" + # Resolve tip commit SHA of the target branch. For push events this + # matches github.sha, but for workflow_dispatch github.sha points at + # the launch ref (typically the default branch), not the branch that + # html-docs/spec-docs actually check out. Resolving here ensures + # metadata.json and the steel-website dispatch payload always + # reference the commit that was built. + if [ "$IS_DEPLOY" = "true" ] && [ "$SHOULD_PUBLISH" = "true" ]; then + COMMIT_SHA=$(git ls-remote "https://github.com/${GITHUB_REPOSITORY}.git" \ + "refs/heads/${BRANCH_INPUT}" | awk '{print $1}') + if [ -z "$COMMIT_SHA" ]; then + echo "ERROR: could not resolve commit SHA for branch '${BRANCH_INPUT}'" + exit 1 + fi + echo "commit_sha=$COMMIT_SHA" >> "$GITHUB_OUTPUT" + fi + # Write job summary { echo "## Check Should Publish" @@ -220,6 +237,7 @@ jobs: - name: Stage combined artifact env: BRANCH: ${{ needs.check-should-publish.outputs.branch }} + COMMIT_SHA: ${{ needs.check-should-publish.outputs.commit_sha }} run: | mkdir -p "stage/${BRANCH}/spec" @@ -233,8 +251,8 @@ jobs: cat > "stage/${BRANCH}/metadata.json" < Date: Wed, 15 Apr 2026 14:58:52 +0200 Subject: [PATCH 08/27] chore(docs): remove inert `edit_uri` The `edit_uri` value has no effect: mkdocs-material only renders the "edit this page" pencil when the theme feature `content.action.edit` is enabled, which this config does not enable. Drop the unused setting to avoid a stale reference to `forks/amsterdam` once docs are published for additional branches. --- mkdocs.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 14cc67b47ca..ec9a528d299 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -3,7 +3,6 @@ site_description: The Ethereum Execution Layer Specifications and Tests site_url: !ENV [SITE_URL, "https://steel.ethereum.foundation/docs/"] repo_url: https://github.com/ethereum/execution-specs repo_name: execution-specs -edit_uri: edit/forks/amsterdam/docs/ copyright: "Copyright: 2026, Ethereum Community" plugins: From 8fce2e5114357522fdc53144035d02a60eafaa75 Mon Sep 17 00:00:00 2001 From: danceratopz Date: Wed, 15 Apr 2026 14:59:18 +0200 Subject: [PATCH 09/27] fix(ci): fail loud when docs allowlist is empty or unreadable Previously the empty-allowlist branch wrote `should_publish=false` and exited 0, silently no-op'ing all downstream publishing. `exit 1` surfaces a misconfigured or missing `.github/configs/docs-branches.yaml` as a failed check instead. --- .github/workflows/docs-build.yaml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/docs-build.yaml b/.github/workflows/docs-build.yaml index bd34e6f0d32..353b0890fed 100644 --- a/.github/workflows/docs-build.yaml +++ b/.github/workflows/docs-build.yaml @@ -93,8 +93,7 @@ jobs: if [ -z "$ALLOWLISTED_BRANCHES" ]; then echo "ERROR: Could not read allowlist from .github/configs/docs-branches.yaml" - echo "should_publish=false" >> "$GITHUB_OUTPUT" - exit 0 + exit 1 fi # Check if branch is in allowlist From ea6a98923288d330c8faa111b2ad9ec8c0c81407 Mon Sep 17 00:00:00 2001 From: danceratopz Date: Thu, 23 Apr 2026 00:11:03 +0100 Subject: [PATCH 10/27] chore(ci): move lint-md and changelog to docs-build.yaml --- .github/workflows/docs-build.yaml | 25 +++++++++++++++-- .github/workflows/test-docs.yaml | 45 ------------------------------- 2 files changed, 23 insertions(+), 47 deletions(-) delete mode 100644 .github/workflows/test-docs.yaml diff --git a/.github/workflows/docs-build.yaml b/.github/workflows/docs-build.yaml index 353b0890fed..b788d92d1e4 100644 --- a/.github/workflows/docs-build.yaml +++ b/.github/workflows/docs-build.yaml @@ -28,8 +28,7 @@ on: - "static/**" - "docs/**" - "packages/testing/**" - - "CONTRIBUTING.md" - - "SECURITY.md" + - "*.md" - "mkdocs.yml" - "uv.lock" - "pyproject.toml" @@ -54,9 +53,31 @@ permissions: contents: read jobs: + lint-md: + name: "Lint Markdown" + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + # TODO: Still on node20 — update when upstream releases a node22+ version + - uses: DavidAnson/markdownlint-cli2-action@07035fd053f7be764496c0f8d8f9f41f98305101 # v22.0.0 + with: + globs: | + docs/**/*.md + *.md + + changelog: + name: "Validate Changelog Entries" + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + - uses: ./.github/actions/setup-uv + - name: Run changelog validation + run: just changelog + check-should-publish: name: "Check Should Publish" runs-on: ubuntu-latest + needs: [lint-md, changelog] outputs: should_publish: ${{ steps.check.outputs.should_publish }} branch: ${{ steps.check.outputs.branch }} diff --git a/.github/workflows/test-docs.yaml b/.github/workflows/test-docs.yaml deleted file mode 100644 index 3b445ff26c4..00000000000 --- a/.github/workflows/test-docs.yaml +++ /dev/null @@ -1,45 +0,0 @@ -name: Static Doc Checks - -on: - push: - branches: - - mainnet - - "forks/**" - paths: &docs_validation_paths - - uv.lock - - CONTRIBUTING.md - - SECURITY.md - - "docs/**" - - "packages/testing/**" - - ".github/workflows/test-docs.yaml" - pull_request: - paths: *docs_validation_paths - workflow_dispatch: - -concurrency: - group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} - cancel-in-progress: true - -jobs: - changelog: - name: Validate changelog entries - runs-on: ubuntu-latest - steps: - - name: Checkout ethereum/execution-specs - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - - uses: ./.github/actions/setup-uv - - name: Run changelog validation - run: just changelog - - lint-md: - name: Lint markdown files with markdownlint - runs-on: ubuntu-latest - steps: - - name: Checkout ethereum/execution-specs - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - # TODO: Still on node20 — update when upstream releases a node22+ version - - uses: DavidAnson/markdownlint-cli2-action@07035fd053f7be764496c0f8d8f9f41f98305101 # v22.0.0 - with: - globs: | - docs/**/*.md - *.md From 5613749b62415dc2d1db9d846fe394a41727f22d Mon Sep 17 00:00:00 2001 From: danceratopz Date: Thu, 23 Apr 2026 00:34:51 +0100 Subject: [PATCH 11/27] refactor(docs): nest rendered spec reference under /specs/reference/ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Previously staged at `/docs//spec/` as a top-level sibling of the mkdocs site. Nest under `/docs//specs/reference/` so the URL mirrors the nav hierarchy (reference now lives inside the Specifications section). Add a "Reference" entry to the literate nav and update the home page card to link at the new path. Both use a ↗ glyph to signal the reference is a separate artifact. The home page link opens in a new tab via `attr_list`; the nav link does not, since `literate-nav` does not honor `attr_list`. Also add a placeholder at `docs/specs/reference/index.md` so mkdocs's strict-mode nav validation succeeds. At deploy time, the `docc` output overwrites the placeholder via `rsync`; locally it points users at `just docs-spec`. --- .github/workflows/docs-build.yaml | 16 ++++++++-------- docs/index.md | 2 +- docs/navigation.md | 1 + docs/specs/reference/index.md | 11 +++++++++++ 4 files changed, 21 insertions(+), 9 deletions(-) create mode 100644 docs/specs/reference/index.md diff --git a/.github/workflows/docs-build.yaml b/.github/workflows/docs-build.yaml index b788d92d1e4..b30e876ddd7 100644 --- a/.github/workflows/docs-build.yaml +++ b/.github/workflows/docs-build.yaml @@ -6,10 +6,10 @@ # the aggregator workflow in steel-website for deployment # # Site structure at steel.ethereum.foundation/docs/: -# /docs/ - Default branch docs (mirrored) -# /docs/spec/ - Default branch spec (mirrored) -# /docs// - Branch-specific docs -# /docs//spec - Branch-specific spec +# /docs/ - Default branch docs (mirrored) +# /docs/specs/reference/ - Default branch spec reference (mirrored) +# /docs// - Branch-specific docs +# /docs//specs/reference - Branch-specific spec reference (docc output) name: Build Docs @@ -264,8 +264,8 @@ jobs: # HTML docs at root of branch directory rsync -a html-docs/ "stage/${BRANCH}/" - # Spec docs in spec/ subdirectory - rsync -a spec-docs/ "stage/${BRANCH}/spec/" + # Spec reference (docc output) nested under specs/ to mirror nav hierarchy + rsync -a spec-docs/ "stage/${BRANCH}/specs/reference/" # Build metadata cat > "stage/${BRANCH}/metadata.json" < Date: Thu, 23 Apr 2026 00:45:51 +0100 Subject: [PATCH 12/27] fix(docs): resolve relative links by adding explicit `.md` suffix Mkdocs treats bare directory URLs (`tests/`, `specs/reference/`) as potential external references and emits INFO-level "unrecognized relative link" messages, leaving the link text as-is. Suffixing with `.md` or `index.md` lets mkdocs resolve the link cleanly and emit the correct URL; the sibling cards in the home page already use this form. Fixes: - `tests/` -> `tests/index.md` in the home page card. - `specs/reference/` -> `specs/reference/index.md` in the home page card and the literate nav entry (now resolves against the stub page added alongside the path rename). - `../tests/prague/.../test_invalid/` -> `.../test_invalid.md` in `writing_tests/post_mortems.md`. --- docs/index.md | 4 ++-- docs/navigation.md | 2 +- docs/writing_tests/post_mortems.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/index.md b/docs/index.md index 02c3e3ae554..c16b008cb7f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -56,7 +56,7 @@ EELS is a collaborative effort between Ethereum Improvement Proposals (EIP) auth Browse the rendered Python specifications for the current fork and EIP. - [:octicons-arrow-right-24: Reference ↗](specs/reference/){target=_blank rel=noopener} + [:octicons-arrow-right-24: Reference ↗](specs/reference/index.md){target=_blank rel=noopener} - :material-format-list-checks: **Test Case Reference** @@ -64,7 +64,7 @@ EELS is a collaborative effort between Ethereum Improvement Proposals (EIP) auth Browse all test cases organized by fork and EIP. - [:octicons-arrow-right-24: Browse tests](tests/) + [:octicons-arrow-right-24: Browse tests](tests/index.md) diff --git a/docs/navigation.md b/docs/navigation.md index 5fdcd9ce87a..e5344212474 100644 --- a/docs/navigation.md +++ b/docs/navigation.md @@ -11,7 +11,7 @@ * [Installation Troubleshooting](getting_started/installation_troubleshooting.md) * [Getting Help](getting_started/getting_help.md) * [Specifications](specs/index.md) - * [Reference ↗](specs/reference/) + * [Reference ↗](specs/reference/index.md) * [Writing Specs](specs/writing_specs.md) * [Adding a New EIP](specs/adding_a_new_eip.md) * [Spec Releases](specs/spec_releases.md) diff --git a/docs/writing_tests/post_mortems.md b/docs/writing_tests/post_mortems.md index b9f5dd0ec30..5c18ef41fd4 100644 --- a/docs/writing_tests/post_mortems.md +++ b/docs/writing_tests/post_mortems.md @@ -78,7 +78,7 @@ IDs of the tests added that now cover the missed scenario and link to the docume *Example:* -- [`tests/prague/eip2537_bls_12_381_precompiles/test_bls12_g1msm.py::test_invalid\[fork_Prague-state_test---bls_g1_truncated_input-\]`](../tests/prague/eip2537_bls_12_381_precompiles/test_bls12_g1msm/test_invalid/) +- [`tests/prague/eip2537_bls_12_381_precompiles/test_bls12_g1msm.py::test_invalid\[fork_Prague-state_test---bls_g1_truncated_input-\]`](../tests/prague/eip2537_bls_12_381_precompiles/test_bls12_g1msm/test_invalid.md) ### Framework/Documentation Changes From 6208a3b775afd16acc8f23de5053ed59ad921645 Mon Sep 17 00:00:00 2001 From: danceratopz Date: Thu, 23 Apr 2026 01:06:49 +0100 Subject: [PATCH 13/27] test(docs): temporarily widen workflow for E2E testing Add `experiments/**` branch trigger and `experiments/publish-docs` to the allowlist so the full pipeline (including `combine` and `trigger-aggregator`) runs on push. Revert before merge. --- .github/configs/docs-branches.yaml | 3 +++ .github/workflows/docs-build.yaml | 1 + 2 files changed, 4 insertions(+) diff --git a/.github/configs/docs-branches.yaml b/.github/configs/docs-branches.yaml index 98843e83a57..95d26923140 100644 --- a/.github/configs/docs-branches.yaml +++ b/.github/configs/docs-branches.yaml @@ -12,3 +12,6 @@ default: "forks/amsterdam" branches: - path: "forks/amsterdam" label: "Amsterdam" + # TEMPORARY: remove after E2E testing + - path: "experiments/publish-docs" + label: "Amsterdam" diff --git a/.github/workflows/docs-build.yaml b/.github/workflows/docs-build.yaml index b30e876ddd7..54f8c88c994 100644 --- a/.github/workflows/docs-build.yaml +++ b/.github/workflows/docs-build.yaml @@ -21,6 +21,7 @@ on: - "devnets/**" - "eips/**" - "projects/**" + - "experiments/**" # TEMPORARY: remove after E2E testing paths: &docs_paths - "src/ethereum/**" - "src/ethereum_spec_tools/docc.py" From b10e61e221d30310cb493bcca7d1449caf551816 Mon Sep 17 00:00:00 2001 From: danceratopz Date: Thu, 23 Apr 2026 01:40:42 +0100 Subject: [PATCH 14/27] fix(docs): force reference nav links to open in a new tab Material's `navigation.instant` (`mkdocs.yml:51`) intercepts internal nav clicks and XHR-swaps the target page into the current DOM. The `docc`-rendered reference at `/specs/reference/` has no Material template markers, so the swap silently fails: the URL and `` update to the reference page but the body stays on the original. Clicking "Reference" from the sidebar or the footer next/prev buttons on `/specs/` appears to do nothing. The home page card already opens in a new tab via `attr_list` (`{target=_blank rel=noopener}`), which makes instant-nav opt out and do a full-page load. `attr_list` doesn't carry through `literate-nav` or the footer template, so add an `on_post_page` hook that rewrites any rendered anchor pointing at the reference (`reference/`, `../reference/`, `specs/reference/`, `../../specs/reference/`, etc.) to include `target="_blank" rel="noopener"`, skipping links that already have the attribute set. --- docs/hooks/reference_new_tab.py | 34 +++++++++++++++++++++++++++++++++ mkdocs.yml | 3 +++ 2 files changed, 37 insertions(+) create mode 100644 docs/hooks/reference_new_tab.py diff --git a/docs/hooks/reference_new_tab.py b/docs/hooks/reference_new_tab.py new file mode 100644 index 00000000000..97937b0be4b --- /dev/null +++ b/docs/hooks/reference_new_tab.py @@ -0,0 +1,34 @@ +""" +Add `target="_blank"` to links pointing at the `docc`-rendered reference. + +Without this, Material's `navigation.instant` intercepts clicks and tries to +XHR-swap the target page into the current DOM, which fails silently because +`docc`'s HTML does not match Material's template markers: the URL and title +update but the body stays on the original page. `target="_blank"` makes +instant-nav opt out and forces a full-page load, matching the home page card +that already sets the attribute via `attr_list`. + +Matches every relative href form mkdocs emits for the reference page across +page depths (e.g., `reference/`, `../reference/`, `specs/reference/`, +`../../specs/reference/`). The trailing slash after `reference` prevents +matching unrelated paths like `reference_specification/`. +""" + +import re + +_A_TAG_REF = re.compile( + r'<a\s+([^>]*?href="(?:\.\./)*(?:specs/)?reference/(?:index\.html)?"[^>]*?)>' +) + + +def _rewrite(match: "re.Match[str]") -> str: + attrs = match.group(1) + if "target=" in attrs: + return match.group(0) + return f'<a {attrs} target="_blank" rel="noopener">' + + +def on_post_page(output: str, page, config) -> str: + """Rewrite anchor tags pointing at the reference to open in a new tab.""" + del page, config + return _A_TAG_REF.sub(_rewrite, output) diff --git a/mkdocs.yml b/mkdocs.yml index ec9a528d299..c525292961c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -31,6 +31,9 @@ plugins: - literate-nav: nav_file: navigation.md +hooks: + - docs/hooks/reference_new_tab.py + watch: - CONTRIBUTING.md - SECURITY.md From 2d764093fc93ddcdb9e41bdfe727245c6b3942ee Mon Sep 17 00:00:00 2001 From: danceratopz <danceratopz@gmail.com> Date: Thu, 23 Apr 2026 08:16:57 +0100 Subject: [PATCH 15/27] chore(ci): remove test config; ready for merge Revert the `experiments/**` branch trigger and the `experiments/publish-docs` allowlist entry added in `6208a3b775a` for E2E testing. Intentionally not dropping original commits for transparency. --- .github/configs/docs-branches.yaml | 3 --- .github/workflows/docs-build.yaml | 1 - 2 files changed, 4 deletions(-) diff --git a/.github/configs/docs-branches.yaml b/.github/configs/docs-branches.yaml index 95d26923140..98843e83a57 100644 --- a/.github/configs/docs-branches.yaml +++ b/.github/configs/docs-branches.yaml @@ -12,6 +12,3 @@ default: "forks/amsterdam" branches: - path: "forks/amsterdam" label: "Amsterdam" - # TEMPORARY: remove after E2E testing - - path: "experiments/publish-docs" - label: "Amsterdam" diff --git a/.github/workflows/docs-build.yaml b/.github/workflows/docs-build.yaml index 54f8c88c994..b30e876ddd7 100644 --- a/.github/workflows/docs-build.yaml +++ b/.github/workflows/docs-build.yaml @@ -21,7 +21,6 @@ on: - "devnets/**" - "eips/**" - "projects/**" - - "experiments/**" # TEMPORARY: remove after E2E testing paths: &docs_paths - "src/ethereum/**" - "src/ethereum_spec_tools/docc.py" From 4eeeb7ee781cb5cb41bb8660a61e6359f3a48350 Mon Sep 17 00:00:00 2001 From: danceratopz <danceratopz@gmail.com> Date: Thu, 23 Apr 2026 09:01:21 +0100 Subject: [PATCH 16/27] feat(ci): add `ref` and `publish` inputs to docs-build dispatch Let maintainers publish or preview docs for any tagged/branched commit without waiting for a push to an allowlisted branch. Dispatch now takes: - `branch` (string, required, default `forks/amsterdam`): Branch to publish under. Must be in the allowlist at `.github/configs/docs-branches.yaml`; `check-should-publish` validates and prints the allowlist into the job summary on mismatch. Kept as `type: string` rather than `type: choice` so the allowlist YAML stays the single source of truth; adding a branch is a one-file edit. - `ref` (string, optional): Branch, tag, or commit SHA to build. Empty falls back to the branch tip. Resolved to a concrete SHA up front via `gh api repos/{owner}/{repo}/commits/{ref}`, so `metadata.json` and the aggregator payload always reference the commit that was built. - `publish` (boolean, default true): When false, `html-docs` and `spec-docs` still run and upload their per-job artifacts, but `combine` and `trigger-aggregator` are skipped. Use for dry-run / artifact inspection without deploying. `html-docs` and `spec-docs` now check out the resolved SHA rather than the branch name, which lines up the build jobs with the SHA recorded in metadata and dispatched to steel-website. The job summary also echoes the expected deploy URL on a publishing run, with a note that resolution is gated on steel-website's own `BRANCH_CONFIG` (`deploy.yml`). --- .github/workflows/docs-build.yaml | 62 +++++++++++++++++++++++-------- 1 file changed, 46 insertions(+), 16 deletions(-) diff --git a/.github/workflows/docs-build.yaml b/.github/workflows/docs-build.yaml index b30e876ddd7..4cbd7dd0fd6 100644 --- a/.github/workflows/docs-build.yaml +++ b/.github/workflows/docs-build.yaml @@ -41,9 +41,20 @@ on: workflow_dispatch: inputs: branch: - description: "Branch to build (must be allowlisted)" + description: "Branch to publish under. Must be in the allowlist (see .github/configs/docs-branches.yaml)." + required: true + type: string + default: forks/amsterdam + ref: + description: "Ref to build: branch name, tag (e.g. v1.2.3), or commit SHA. Empty = tip of the branch above." required: false type: string + default: "" + publish: + description: "Combine artifacts and deploy to steel.ethereum.foundation. Untick to dry-run (build-only)." + required: true + type: boolean + default: true concurrency: group: docs-build-${{ github.ref }} @@ -94,7 +105,10 @@ jobs: id: check env: BRANCH_INPUT: ${{ github.event.inputs.branch || github.ref_name }} + REF_INPUT: ${{ github.event.inputs.ref }} + PUBLISH_INPUT: ${{ github.event.inputs.publish }} EVENT_NAME: ${{ github.event_name }} + GH_TOKEN: ${{ github.token }} run: | echo "branch=$BRANCH_INPUT" >> "$GITHUB_OUTPUT" @@ -102,9 +116,14 @@ jobs: BRANCH_ARTIFACT_NAME="${BRANCH_INPUT//\//-}" echo "branch_artifact_name=$BRANCH_ARTIFACT_NAME" >> "$GITHUB_OUTPUT" - # Deploy on push and workflow_dispatch, not on PRs + # Deploy on push, or workflow_dispatch with publish=true. PRs never + # publish. A dispatch with publish=false still builds html-docs and + # spec-docs (uploaded as per-job artifacts) but skips combine and + # the aggregator trigger. IS_DEPLOY="false" - if [ "$EVENT_NAME" = "push" ] || [ "$EVENT_NAME" = "workflow_dispatch" ]; then + if [ "$EVENT_NAME" = "push" ]; then + IS_DEPLOY="true" + elif [ "$EVENT_NAME" = "workflow_dispatch" ] && [ "$PUBLISH_INPUT" = "true" ]; then IS_DEPLOY="true" fi echo "is_deploy=$IS_DEPLOY" >> "$GITHUB_OUTPUT" @@ -125,17 +144,18 @@ jobs: fi echo "should_publish=$SHOULD_PUBLISH" >> "$GITHUB_OUTPUT" - # Resolve tip commit SHA of the target branch. For push events this - # matches github.sha, but for workflow_dispatch github.sha points at - # the launch ref (typically the default branch), not the branch that - # html-docs/spec-docs actually check out. Resolving here ensures - # metadata.json and the steel-website dispatch payload always - # reference the commit that was built. - if [ "$IS_DEPLOY" = "true" ] && [ "$SHOULD_PUBLISH" = "true" ]; then - COMMIT_SHA=$(git ls-remote "https://github.com/${GITHUB_REPOSITORY}.git" \ - "refs/heads/${BRANCH_INPUT}" | awk '{print $1}') + # Resolve the ref we will actually check out and build. On dispatch, + # the user can specify any branch/tag/SHA; empty falls back to the + # target branch tip. For push, we always build the pushed ref. + # Resolving to a concrete SHA here keeps metadata.json and the + # aggregator dispatch payload consistent with what the build jobs + # check out, even when github.sha points at a different ref (which + # happens for workflow_dispatch launched from the default branch). + if [ "$EVENT_NAME" != "pull_request" ] && [ "$SHOULD_PUBLISH" = "true" ]; then + RESOLVE_REF="${REF_INPUT:-$BRANCH_INPUT}" + COMMIT_SHA=$(gh api "repos/${GITHUB_REPOSITORY}/commits/${RESOLVE_REF}" --jq .sha 2>/dev/null || true) if [ -z "$COMMIT_SHA" ]; then - echo "ERROR: could not resolve commit SHA for branch '${BRANCH_INPUT}'" + echo "ERROR: could not resolve commit SHA for ref '${RESOLVE_REF}'" exit 1 fi echo "commit_sha=$COMMIT_SHA" >> "$GITHUB_OUTPUT" @@ -148,6 +168,12 @@ jobs: echo "| Setting | Value |" echo "|---------|-------|" echo "| **Branch** | \`$BRANCH_INPUT\` |" + if [ -n "$REF_INPUT" ]; then + echo "| **Ref** | \`$REF_INPUT\` |" + fi + if [ -n "${COMMIT_SHA:-}" ]; then + echo "| **Resolved SHA** | \`${COMMIT_SHA:0:7}\` |" + fi echo "| **Event** | \`$EVENT_NAME\` |" echo "| **Deploy build** | $IS_DEPLOY |" echo "| **Allowlisted** | $SHOULD_PUBLISH |" @@ -155,8 +181,12 @@ jobs: if [ "$EVENT_NAME" = "pull_request" ]; then echo "-> **Build only** -- pull request; artifacts are not published." + elif [ "$EVENT_NAME" = "workflow_dispatch" ] && [ "$PUBLISH_INPUT" != "true" ]; then + echo "-> **Build only** -- \`publish\` input is false; \`html-docs\` and \`spec-docs\` artifacts are uploaded but not combined or dispatched." elif [ "$SHOULD_PUBLISH" = "true" ]; then - echo "-> **Will publish** -- branch is allowlisted; artifacts will be built, combined, and uploaded." + echo "-> **Will publish** at <https://steel.ethereum.foundation/docs/${BRANCH_INPUT}/>" + echo "" + echo "_Note: the URL only resolves if \`${BRANCH_INPUT}\` is also configured in steel-website's \`BRANCH_CONFIG\` (\`deploy.yml\`). If not, the aggregator will receive the dispatch but drop the artifact._" else echo "-> **Skipping publish** -- branch is not in the allowlist (\`.github/configs/docs-branches.yaml\`)." echo "" @@ -177,7 +207,7 @@ jobs: steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 with: - ref: ${{ github.event_name == 'workflow_dispatch' && needs.check-should-publish.outputs.branch || '' }} + ref: ${{ github.event_name == 'workflow_dispatch' && needs.check-should-publish.outputs.commit_sha || '' }} fetch-depth: 0 submodules: recursive @@ -215,7 +245,7 @@ jobs: steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 with: - ref: ${{ github.event_name == 'workflow_dispatch' && needs.check-should-publish.outputs.branch || '' }} + ref: ${{ github.event_name == 'workflow_dispatch' && needs.check-should-publish.outputs.commit_sha || '' }} fetch-depth: 0 submodules: recursive From 3496b74b57bc142ca26ee945dbed345a6497c734 Mon Sep 17 00:00:00 2001 From: danceratopz <danceratopz@gmail.com> Date: Thu, 23 Apr 2026 09:01:21 +0100 Subject: [PATCH 17/27] chore(ci): allowlist `devnets/bal/4` for docs publishing Adds `devnets/bal/4` (label `bal-devnet-4`) to the publish allowlist and the site's version switcher so pushes to that branch publish at `/docs/devnets/bal/4/`. --- .github/configs/docs-branches.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/configs/docs-branches.yaml b/.github/configs/docs-branches.yaml index 98843e83a57..d66ca8edf4b 100644 --- a/.github/configs/docs-branches.yaml +++ b/.github/configs/docs-branches.yaml @@ -12,3 +12,5 @@ default: "forks/amsterdam" branches: - path: "forks/amsterdam" label: "Amsterdam" + - path: "devnets/bal/4" + label: "bal-devnet-4" From 3f37fa12729490377ce26f9765d68167de0e473c Mon Sep 17 00:00:00 2001 From: danceratopz <danceratopz@gmail.com> Date: Thu, 23 Apr 2026 23:58:34 +0100 Subject: [PATCH 18/27] refactor(ci): drop `publish` dispatch input and `is_deploy` output The `publish` boolean on `workflow_dispatch` was intended as a dry-run (build without deploying), but PRs already exercise the build path and local `just docs`/`just docs-spec` cover ref-specific builds. It was also silently broken: the upload steps gated on `is_deploy == 'true'`, so `publish=false` produced no artifacts despite the summary claiming otherwise. With `publish` gone, `is_deploy` becomes redundant with `should_publish` on every gate, so collapse both into a single `should_publish` check across the upload steps, `combine`, and `trigger-aggregator`. Drop the `Deploy build` row from the check-should-publish summary. --- .github/workflows/docs-build.yaml | 34 ++++++------------------------- 1 file changed, 6 insertions(+), 28 deletions(-) diff --git a/.github/workflows/docs-build.yaml b/.github/workflows/docs-build.yaml index 4cbd7dd0fd6..7a0033c35b3 100644 --- a/.github/workflows/docs-build.yaml +++ b/.github/workflows/docs-build.yaml @@ -50,11 +50,6 @@ on: required: false type: string default: "" - publish: - description: "Combine artifacts and deploy to steel.ethereum.foundation. Untick to dry-run (build-only)." - required: true - type: boolean - default: true concurrency: group: docs-build-${{ github.ref }} @@ -93,7 +88,6 @@ jobs: should_publish: ${{ steps.check.outputs.should_publish }} branch: ${{ steps.check.outputs.branch }} branch_artifact_name: ${{ steps.check.outputs.branch_artifact_name }} - is_deploy: ${{ steps.check.outputs.is_deploy }} commit_sha: ${{ steps.check.outputs.commit_sha }} steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 @@ -106,7 +100,6 @@ jobs: env: BRANCH_INPUT: ${{ github.event.inputs.branch || github.ref_name }} REF_INPUT: ${{ github.event.inputs.ref }} - PUBLISH_INPUT: ${{ github.event.inputs.publish }} EVENT_NAME: ${{ github.event_name }} GH_TOKEN: ${{ github.token }} run: | @@ -116,18 +109,6 @@ jobs: BRANCH_ARTIFACT_NAME="${BRANCH_INPUT//\//-}" echo "branch_artifact_name=$BRANCH_ARTIFACT_NAME" >> "$GITHUB_OUTPUT" - # Deploy on push, or workflow_dispatch with publish=true. PRs never - # publish. A dispatch with publish=false still builds html-docs and - # spec-docs (uploaded as per-job artifacts) but skips combine and - # the aggregator trigger. - IS_DEPLOY="false" - if [ "$EVENT_NAME" = "push" ]; then - IS_DEPLOY="true" - elif [ "$EVENT_NAME" = "workflow_dispatch" ] && [ "$PUBLISH_INPUT" = "true" ]; then - IS_DEPLOY="true" - fi - echo "is_deploy=$IS_DEPLOY" >> "$GITHUB_OUTPUT" - # Extract branch paths from allowlist config ALLOWLISTED_BRANCHES=$(yq '.branches[].path' .github/configs/docs-branches.yaml 2>/dev/null || echo "") @@ -175,14 +156,11 @@ jobs: echo "| **Resolved SHA** | \`${COMMIT_SHA:0:7}\` |" fi echo "| **Event** | \`$EVENT_NAME\` |" - echo "| **Deploy build** | $IS_DEPLOY |" echo "| **Allowlisted** | $SHOULD_PUBLISH |" echo "" if [ "$EVENT_NAME" = "pull_request" ]; then echo "-> **Build only** -- pull request; artifacts are not published." - elif [ "$EVENT_NAME" = "workflow_dispatch" ] && [ "$PUBLISH_INPUT" != "true" ]; then - echo "-> **Build only** -- \`publish\` input is false; \`html-docs\` and \`spec-docs\` artifacts are uploaded but not combined or dispatched." elif [ "$SHOULD_PUBLISH" = "true" ]; then echo "-> **Will publish** at <https://steel.ethereum.foundation/docs/${BRANCH_INPUT}/>" echo "" @@ -216,9 +194,9 @@ jobs: - name: Build MkDocs documentation env: BRANCH: ${{ needs.check-should-publish.outputs.branch }} - IS_DEPLOY: ${{ needs.check-should-publish.outputs.is_deploy }} + SHOULD_PUBLISH: ${{ needs.check-should-publish.outputs.should_publish }} run: | - if [ "$IS_DEPLOY" = "true" ]; then + if [ "$SHOULD_PUBLISH" = "true" ]; then export SITE_URL="https://steel.ethereum.foundation/docs/${BRANCH}/" else export SITE_URL="https://example.com/docs/${BRANCH}/" @@ -228,7 +206,7 @@ jobs: just docs - name: Upload HTML docs artifact - if: needs.check-should-publish.outputs.is_deploy == 'true' + if: needs.check-should-publish.outputs.should_publish == 'true' uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0 with: name: docs-html-${{ needs.check-should-publish.outputs.branch_artifact_name }} @@ -257,7 +235,7 @@ jobs: DOCC_SKIP_DIFFS: ${{ case(github.event_name == 'push' && github.ref_name == github.event.repository.default_branch, '', '1') }} - name: Upload spec docs artifact - if: needs.check-should-publish.outputs.is_deploy == 'true' + if: needs.check-should-publish.outputs.should_publish == 'true' uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0 with: name: docs-spec-${{ needs.check-should-publish.outputs.branch_artifact_name }} @@ -269,7 +247,7 @@ jobs: name: "Combine and Upload" runs-on: ubuntu-latest needs: [check-should-publish, html-docs, spec-docs] - if: needs.check-should-publish.outputs.is_deploy == 'true' && needs.check-should-publish.outputs.should_publish == 'true' + if: needs.check-should-publish.outputs.should_publish == 'true' steps: - name: Download HTML docs artifact @@ -339,7 +317,7 @@ jobs: name: "Trigger Aggregator" runs-on: ubuntu-latest needs: [check-should-publish, combine] - if: needs.check-should-publish.outputs.is_deploy == 'true' && needs.check-should-publish.outputs.should_publish == 'true' + if: needs.check-should-publish.outputs.should_publish == 'true' steps: - name: Trigger steel-website aggregator workflow From 743c621f70e2f59659b8a52537848670f687dfa4 Mon Sep 17 00:00:00 2001 From: danceratopz <danceratopz@gmail.com> Date: Thu, 23 Apr 2026 23:59:22 +0100 Subject: [PATCH 19/27] fix(ci): create `specs/reference/` before staging spec docs The spec-docs `rsync` targets `stage/${BRANCH}/specs/reference/`, but the preceding `mkdir -p` still created `stage/${BRANCH}/spec` (singular, leftover from the pre-`specs/reference/` layout). It worked by accident because the prior `rsync -a html-docs/` copied mkdocs's `specs/` subtree into the stage, so the intermediate directory happened to exist by the time the spec-docs rsync ran. Create the exact target path up front so the staging step no longer depends on mkdocs output shape. --- .github/workflows/docs-build.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs-build.yaml b/.github/workflows/docs-build.yaml index 7a0033c35b3..f6631678ab0 100644 --- a/.github/workflows/docs-build.yaml +++ b/.github/workflows/docs-build.yaml @@ -267,7 +267,7 @@ jobs: BRANCH: ${{ needs.check-should-publish.outputs.branch }} COMMIT_SHA: ${{ needs.check-should-publish.outputs.commit_sha }} run: | - mkdir -p "stage/${BRANCH}/spec" + mkdir -p "stage/${BRANCH}/specs/reference" # HTML docs at root of branch directory rsync -a html-docs/ "stage/${BRANCH}/" From 9429469674899e8b548d0a22535d5b224f5fb1d4 Mon Sep 17 00:00:00 2001 From: danceratopz <danceratopz@gmail.com> Date: Fri, 24 Apr 2026 00:12:48 +0100 Subject: [PATCH 20/27] chore(docs): namespace docs URL under `/docs/execution-specs/` `steel-website` serves docs for multiple repos under `steel.ethereum.foundation/docs/<repo>/`. Prefix every URL we publish or reference with `execution-specs` so the built site, dispatched artifacts, and documented links resolve under the correct namespace. Updated: - `mkdocs.yml` `site_url` fallback. - `DocsConfig.DOCS_BASE_URL` (ruff-formatted onto its own line). - `README.md` docs link. - `docs/dev/docs.md` hosting URL. - `.github/workflows/docs-build.yaml` site-structure comment, `Will publish` job summary URL, and `SITE_URL` export. - `.github/configs/docs-branches.yaml` comment header. --- .github/configs/docs-branches.yaml | 2 +- .github/workflows/docs-build.yaml | 14 +++++++------- README.md | 2 +- docs/dev/docs.md | 2 +- mkdocs.yml | 2 +- .../testing/src/execution_testing/config/docs.py | 4 +++- 6 files changed, 14 insertions(+), 12 deletions(-) diff --git a/.github/configs/docs-branches.yaml b/.github/configs/docs-branches.yaml index d66ca8edf4b..55c5a561811 100644 --- a/.github/configs/docs-branches.yaml +++ b/.github/configs/docs-branches.yaml @@ -1,5 +1,5 @@ # Branches whose documentation is built and published to -# steel.ethereum.foundation/docs/ +# steel.ethereum.foundation/docs/execution-specs/ # # Must stay in sync with steel-website's BRANCH_CONFIG in deploy.yml. # diff --git a/.github/workflows/docs-build.yaml b/.github/workflows/docs-build.yaml index f6631678ab0..18263f640dc 100644 --- a/.github/workflows/docs-build.yaml +++ b/.github/workflows/docs-build.yaml @@ -5,11 +5,11 @@ # - On push to allowlisted branches: Builds, uploads artifacts, and triggers # the aggregator workflow in steel-website for deployment # -# Site structure at steel.ethereum.foundation/docs/: -# /docs/ - Default branch docs (mirrored) -# /docs/specs/reference/ - Default branch spec reference (mirrored) -# /docs/<branch>/ - Branch-specific docs -# /docs/<branch>/specs/reference - Branch-specific spec reference (docc output) +# Site structure at steel.ethereum.foundation/docs/execution-specs/: +# /docs/execution-specs/ - Default branch docs (mirrored) +# /docs/execution-specs/specs/reference/ - Default branch spec reference (mirrored) +# /docs/execution-specs/<branch>/ - Branch-specific docs +# /docs/execution-specs/<branch>/specs/reference - Branch-specific spec reference (docc output) name: Build Docs @@ -162,7 +162,7 @@ jobs: if [ "$EVENT_NAME" = "pull_request" ]; then echo "-> **Build only** -- pull request; artifacts are not published." elif [ "$SHOULD_PUBLISH" = "true" ]; then - echo "-> **Will publish** at <https://steel.ethereum.foundation/docs/${BRANCH_INPUT}/>" + echo "-> **Will publish** at <https://steel.ethereum.foundation/docs/execution-specs/${BRANCH_INPUT}/>" echo "" echo "_Note: the URL only resolves if \`${BRANCH_INPUT}\` is also configured in steel-website's \`BRANCH_CONFIG\` (\`deploy.yml\`). If not, the aggregator will receive the dispatch but drop the artifact._" else @@ -197,7 +197,7 @@ jobs: SHOULD_PUBLISH: ${{ needs.check-should-publish.outputs.should_publish }} run: | if [ "$SHOULD_PUBLISH" = "true" ]; then - export SITE_URL="https://steel.ethereum.foundation/docs/${BRANCH}/" + export SITE_URL="https://steel.ethereum.foundation/docs/execution-specs/${BRANCH}/" else export SITE_URL="https://example.com/docs/${BRANCH}/" fi diff --git a/README.md b/README.md index 16903060dff..06b61ff278f 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ Python 3.11–3.14 are supported; 3.12 tends to be the smoothest for local setup ## Documentation -- **Repo documentation (default branch/fork)**: <https://steel.ethereum.foundation/docs/> +- **Repo documentation (default branch/fork)**: <https://steel.ethereum.foundation/docs/execution-specs/> - **Protocol history**: [docs/specs/protocol_history.md](docs/specs/protocol_history.md) - **Versioning scheme**: [docs/specs/spec_releases.md](docs/specs/spec_releases.md) (PEP 440 compatible; hardfork encoded in the minor version, `rcN` marks devnets). diff --git a/docs/dev/docs.md b/docs/dev/docs.md index a60dc352985..53225b5b6d0 100644 --- a/docs/dev/docs.md +++ b/docs/dev/docs.md @@ -1,6 +1,6 @@ # Documentation -The `execution-specs` documentation is generated via [`mkdocs`](https://www.mkdocs.org/) and (soon) hosted remotely on Github Pages at [steel.ethereum.foundation/docs/](https://steel.ethereum.foundation/docs/). +The `execution-specs` documentation is generated via [`mkdocs`](https://www.mkdocs.org/) and (soon) hosted remotely on Github Pages at [steel.ethereum.foundation/docs/execution-specs/](https://steel.ethereum.foundation/docs/execution-specs/). ## Prerequisites diff --git a/mkdocs.yml b/mkdocs.yml index c525292961c..f5f9fa55257 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,6 +1,6 @@ site_name: Ethereum Execution Specs site_description: The Ethereum Execution Layer Specifications and Tests -site_url: !ENV [SITE_URL, "https://steel.ethereum.foundation/docs/"] +site_url: !ENV [SITE_URL, "https://steel.ethereum.foundation/docs/execution-specs/"] repo_url: https://github.com/ethereum/execution-specs repo_name: execution-specs copyright: "Copyright: 2026, Ethereum Community" diff --git a/packages/testing/src/execution_testing/config/docs.py b/packages/testing/src/execution_testing/config/docs.py index c6e33898f16..21f21a1b5a8 100644 --- a/packages/testing/src/execution_testing/config/docs.py +++ b/packages/testing/src/execution_testing/config/docs.py @@ -17,7 +17,9 @@ class DocsConfig(BaseModel): GENERATE_UNTIL_FORK: str = "Amsterdam" """The fork until which documentation should be generated.""" - DOCS_BASE_URL: str = "https://steel.ethereum.foundation/docs" + DOCS_BASE_URL: str = ( + "https://steel.ethereum.foundation/docs/execution-specs" + ) # Documentation URLs prefixed with `DOCS_URL__` to avoid conflicts with # other URLs From 197daaf2a88fceaccdf28b48413bd05f48f70949 Mon Sep 17 00:00:00 2001 From: danceratopz <danceratopz@gmail.com> Date: Fri, 24 Apr 2026 00:17:54 +0100 Subject: [PATCH 21/27] chore(ci): drop unused `default:` from `docs-branches.yaml` The field was never read by the workflow (which only consumes `.branches[].path`) and doesn't mirror anything on `steel-website` either: its `docs-config.yml` uses a different key (`default_branch:`). Remove the dead entry and tighten the sync-comment so it names the actual source of truth (`docs-config.yml`) and the specific invariant (the `branches[]` list). --- .github/configs/docs-branches.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/configs/docs-branches.yaml b/.github/configs/docs-branches.yaml index 55c5a561811..cab31982f1b 100644 --- a/.github/configs/docs-branches.yaml +++ b/.github/configs/docs-branches.yaml @@ -1,14 +1,14 @@ # Branches whose documentation is built and published to # steel.ethereum.foundation/docs/execution-specs/ # -# Must stay in sync with steel-website's BRANCH_CONFIG in deploy.yml. +# The `branches[]` list must stay in sync with steel-website's +# `docs-config.yml`; a branch that publishes here but isn't listed there +# is dispatched but dropped by the aggregator. # # Each entry defines: # - path: The branch name (must match the Git branch exactly) # - label: Human-readable label for the version switcher UI -default: "forks/amsterdam" - branches: - path: "forks/amsterdam" label: "Amsterdam" From 39d2800680a679f6f4bae14bf1e2ee959e5e2dca Mon Sep 17 00:00:00 2001 From: danceratopz <danceratopz@gmail.com> Date: Fri, 24 Apr 2026 00:20:14 +0100 Subject: [PATCH 22/27] fix(ci): use `GITHUB_SHA` directly on push events `check-should-publish` was always resolving the commit SHA via `gh api repos/.../commits/<branch>`, which on push returns the branch tip at API-call time. If another push lands in the gap between the event firing and the API call, `commit_sha` (written into `metadata.json` and the `steel-website` aggregator dispatch) drifts from the actual commit the build jobs check out: the build jobs fall back to `github.sha`, i.e. the pushed commit. Use `$GITHUB_SHA` directly on push so every artifact and the downstream dispatch references the same commit. Keep the `gh api` resolution for `workflow_dispatch`, where `github.sha` points at whichever ref the dispatch was launched from rather than the user-specified `branch`/`ref`. Concurrency cancellation already shrinks the race window, but this closes it cleanly. --- .github/workflows/docs-build.yaml | 30 ++++++++++++++++++------------ 1 file changed, 18 insertions(+), 12 deletions(-) diff --git a/.github/workflows/docs-build.yaml b/.github/workflows/docs-build.yaml index 18263f640dc..cf3ccc5c76e 100644 --- a/.github/workflows/docs-build.yaml +++ b/.github/workflows/docs-build.yaml @@ -125,19 +125,25 @@ jobs: fi echo "should_publish=$SHOULD_PUBLISH" >> "$GITHUB_OUTPUT" - # Resolve the ref we will actually check out and build. On dispatch, - # the user can specify any branch/tag/SHA; empty falls back to the - # target branch tip. For push, we always build the pushed ref. - # Resolving to a concrete SHA here keeps metadata.json and the - # aggregator dispatch payload consistent with what the build jobs - # check out, even when github.sha points at a different ref (which - # happens for workflow_dispatch launched from the default branch). + # Resolve the concrete SHA we will build, so metadata.json and the + # aggregator dispatch payload match what the build jobs check out. + # + # On push, GITHUB_SHA is the pushed commit; using it avoids a race + # where another push lands between the event and a `gh api` lookup. + # On workflow_dispatch, the user may specify any branch/tag/SHA via + # the `ref` input (empty falls back to the branch tip), and + # github.sha points at whatever ref the dispatch was launched from + # (often the default branch), so we resolve via the API. if [ "$EVENT_NAME" != "pull_request" ] && [ "$SHOULD_PUBLISH" = "true" ]; then - RESOLVE_REF="${REF_INPUT:-$BRANCH_INPUT}" - COMMIT_SHA=$(gh api "repos/${GITHUB_REPOSITORY}/commits/${RESOLVE_REF}" --jq .sha 2>/dev/null || true) - if [ -z "$COMMIT_SHA" ]; then - echo "ERROR: could not resolve commit SHA for ref '${RESOLVE_REF}'" - exit 1 + if [ "$EVENT_NAME" = "push" ]; then + COMMIT_SHA="$GITHUB_SHA" + else + RESOLVE_REF="${REF_INPUT:-$BRANCH_INPUT}" + COMMIT_SHA=$(gh api "repos/${GITHUB_REPOSITORY}/commits/${RESOLVE_REF}" --jq .sha 2>/dev/null || true) + if [ -z "$COMMIT_SHA" ]; then + echo "ERROR: could not resolve commit SHA for ref '${RESOLVE_REF}'" + exit 1 + fi fi echo "commit_sha=$COMMIT_SHA" >> "$GITHUB_OUTPUT" fi From fce3ef505461811920ec52190f39b645a67de8bf Mon Sep 17 00:00:00 2001 From: danceratopz <danceratopz@gmail.com> Date: Fri, 24 Apr 2026 00:21:58 +0100 Subject: [PATCH 23/27] docs: drop `gh-pages` mentions and retarget spec links - `docs/dev/docs.md`: strip the "(soon) hosted remotely on Github Pages" phrasing. The site is now served by `steel-website` under `steel.ethereum.foundation/docs/execution-specs/`. - `docs/specs/index.md`: point the "Rendered specification" entry at the new `specs/reference/` path instead of the `ethereum.github.io/execution-specs/` gh-pages URL. - `docs/specs/writing_specs.md`: retarget the fork "diff outputs" link to the new `specs/reference/diffs/` path. --- docs/dev/docs.md | 2 +- docs/specs/index.md | 2 +- docs/specs/writing_specs.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/dev/docs.md b/docs/dev/docs.md index 53225b5b6d0..96fe14f6044 100644 --- a/docs/dev/docs.md +++ b/docs/dev/docs.md @@ -1,6 +1,6 @@ # Documentation -The `execution-specs` documentation is generated via [`mkdocs`](https://www.mkdocs.org/) and (soon) hosted remotely on Github Pages at [steel.ethereum.foundation/docs/execution-specs/](https://steel.ethereum.foundation/docs/execution-specs/). +The `execution-specs` documentation is generated via [`mkdocs`](https://www.mkdocs.org/) and hosted at [steel.ethereum.foundation/docs/execution-specs/](https://steel.ethereum.foundation/docs/execution-specs/). ## Prerequisites diff --git a/docs/specs/index.md b/docs/specs/index.md index bbe3555553c..a7cdb96f34e 100644 --- a/docs/specs/index.md +++ b/docs/specs/index.md @@ -51,7 +51,7 @@ The trade-off is that a bug fix that applies to every fork must be applied to ev - [Adding a New EIP](adding_a_new_eip.md): the EIP lifecycle from pre-draft to final, and how to land a new EIP in EELS. - [Spec Releases](spec_releases.md): how EELS versions relate to Ethereum hardforks and devnets. - [Protocol History](protocol_history.md): the full table of mainnet hardforks, their included EIPs, and their fork manifests. -- [Rendered specification](https://ethereum.github.io/execution-specs/): the `docc`-rendered narrative view of the Python spec, with side-by-side diffs between forks. +- [Rendered specification](https://steel.ethereum.foundation/docs/execution-specs/specs/reference/): the `docc`-rendered narrative view of the Python spec, with side-by-side diffs between forks. !!! bug "Reporting a vulnerability" Care is required when filing issues or PRs for functionality that is live on Ethereum mainnet. Please report vulnerabilities and verify bounty eligibility via the [bug bounty program](https://bounty.ethereum.org). diff --git a/docs/specs/writing_specs.md b/docs/specs/writing_specs.md index 462dbcd5189..03f862251c6 100644 --- a/docs/specs/writing_specs.md +++ b/docs/specs/writing_specs.md @@ -119,7 +119,7 @@ The marked lines (`<-`) are now incorrectly attributed to EIP-4567 in Fork+1. In ## Changes across multiple forks -Many contributions require changes across multiple forks, organized under `src/ethereum/forks/`. When making such changes, ensure that differences between the forks are minimal and consist only of necessary differences. This produces cleaner [diff outputs](https://ethereum.github.io/execution-specs/diffs/index.html). +Many contributions require changes across multiple forks, organized under `src/ethereum/forks/`. When making such changes, ensure that differences between the forks are minimal and consist only of necessary differences. This produces cleaner [diff outputs](https://steel.ethereum.foundation/docs/execution-specs/specs/reference/diffs/index.html). When creating pull requests affecting multiple forks, we recommend submitting your PR in two steps: From cc7c0654d86bc44743b07c4719f59460d8666d8a Mon Sep 17 00:00:00 2001 From: danceratopz <danceratopz@gmail.com> Date: Fri, 24 Apr 2026 00:23:59 +0100 Subject: [PATCH 24/27] test(docs): temporarily widen workflow for E2E testing Add `experiments/**` to the push trigger and `experiments/publish-docs` to the allowlist so a push to this branch exercises the full pipeline (`combine` and `trigger-aggregator` included) before the PR is marked ready. Revert before merge. --- .github/configs/docs-branches.yaml | 3 +++ .github/workflows/docs-build.yaml | 1 + 2 files changed, 4 insertions(+) diff --git a/.github/configs/docs-branches.yaml b/.github/configs/docs-branches.yaml index cab31982f1b..701afab89f5 100644 --- a/.github/configs/docs-branches.yaml +++ b/.github/configs/docs-branches.yaml @@ -14,3 +14,6 @@ branches: label: "Amsterdam" - path: "devnets/bal/4" label: "bal-devnet-4" + # TEMPORARY: remove after E2E testing + - path: "experiments/publish-docs" + label: "Amsterdam" diff --git a/.github/workflows/docs-build.yaml b/.github/workflows/docs-build.yaml index cf3ccc5c76e..c6a29e9e0ba 100644 --- a/.github/workflows/docs-build.yaml +++ b/.github/workflows/docs-build.yaml @@ -21,6 +21,7 @@ on: - "devnets/**" - "eips/**" - "projects/**" + - "experiments/**" # TEMPORARY: remove after E2E testing paths: &docs_paths - "src/ethereum/**" - "src/ethereum_spec_tools/docc.py" From a6ad4fc72375be4e4d960a904f638f8dc52d9dd0 Mon Sep 17 00:00:00 2001 From: danceratopz <danceratopz@gmail.com> Date: Fri, 24 Apr 2026 00:40:40 +0100 Subject: [PATCH 25/27] chore(ci): remove test config; ready for merge Revert the `experiments/**` branch trigger and the `experiments/publish-docs` allowlist entry added in `cc7c0654d86` for E2E testing. Intentionally not dropping the original commit for transparency. --- .github/configs/docs-branches.yaml | 3 --- .github/workflows/docs-build.yaml | 1 - 2 files changed, 4 deletions(-) diff --git a/.github/configs/docs-branches.yaml b/.github/configs/docs-branches.yaml index 701afab89f5..cab31982f1b 100644 --- a/.github/configs/docs-branches.yaml +++ b/.github/configs/docs-branches.yaml @@ -14,6 +14,3 @@ branches: label: "Amsterdam" - path: "devnets/bal/4" label: "bal-devnet-4" - # TEMPORARY: remove after E2E testing - - path: "experiments/publish-docs" - label: "Amsterdam" diff --git a/.github/workflows/docs-build.yaml b/.github/workflows/docs-build.yaml index c6a29e9e0ba..cf3ccc5c76e 100644 --- a/.github/workflows/docs-build.yaml +++ b/.github/workflows/docs-build.yaml @@ -21,7 +21,6 @@ on: - "devnets/**" - "eips/**" - "projects/**" - - "experiments/**" # TEMPORARY: remove after E2E testing paths: &docs_paths - "src/ethereum/**" - "src/ethereum_spec_tools/docc.py" From b4c4f8d28d66362109a2855ce271bed093fda1c2 Mon Sep 17 00:00:00 2001 From: danceratopz <danceratopz@gmail.com> Date: Sat, 25 Apr 2026 17:04:06 +0200 Subject: [PATCH 26/27] refactor(ci): narrow `docs-build` `push` trigger to auto-publish set Restrict the `push:` trigger to `mainnet` and `forks/amsterdam`. Other allowlisted branches in `.github/configs/docs-branches.yaml` now publish only via `workflow_dispatch` (use the `ref:` input to publish a tag/SHA). The allowlist remains the source of truth for which branches are allowed to publish; this change separates "allowed to publish" from "auto-publishes on push". --- .github/workflows/docs-build.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/docs-build.yaml b/.github/workflows/docs-build.yaml index cf3ccc5c76e..a9617549142 100644 --- a/.github/workflows/docs-build.yaml +++ b/.github/workflows/docs-build.yaml @@ -15,12 +15,12 @@ name: Build Docs on: push: + # Branches that auto-publish on push. Other allowlisted branches in + # .github/configs/docs-branches.yaml publish only via workflow_dispatch + # (use the `ref:` input to publish a tag/SHA). branches: - mainnet - - "forks/**" - - "devnets/**" - - "eips/**" - - "projects/**" + - forks/amsterdam paths: &docs_paths - "src/ethereum/**" - "src/ethereum_spec_tools/docc.py" From 7c9bf7facb1f1fa714e582e07d5732e5ca0d38ad Mon Sep 17 00:00:00 2001 From: danceratopz <danceratopz@gmail.com> Date: Sat, 25 Apr 2026 17:04:17 +0200 Subject: [PATCH 27/27] chore(ci): add `mainnet` entry to docs publish allowlist Add a `mainnet` entry to `.github/configs/docs-branches.yaml` with label `Mainnet (BPO2)` so pushes to `mainnet` (already in the workflow's auto-publish trigger) pass the allowlist gate. Requires a matching entry in `steel-website`'s `BRANCH_CONFIG` for the URL to actually serve. --- .github/configs/docs-branches.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/configs/docs-branches.yaml b/.github/configs/docs-branches.yaml index cab31982f1b..bcc44b6b1dd 100644 --- a/.github/configs/docs-branches.yaml +++ b/.github/configs/docs-branches.yaml @@ -10,6 +10,8 @@ # - label: Human-readable label for the version switcher UI branches: + - path: "mainnet" + label: "Mainnet (BPO2)" - path: "forks/amsterdam" label: "Amsterdam" - path: "devnets/bal/4"