From 07d185e646adfb64ce25a286cfd1293732ceafdb Mon Sep 17 00:00:00 2001 From: Pankaj Koti Date: Mon, 20 Apr 2026 13:28:57 +0530 Subject: [PATCH 1/4] Fix CI failures caused by docs build memory exhaustion The Sphinx docs build had outgrown the memory available on pre-commit.ci runners and was failing consistently on every pull request, including ones that touched no documentation at all. The result was a red pre-commit.ci check on unrelated PRs, blocked merges, time lost to investigating failures that had nothing to do with the change under review, and an erosion of trust in required checks. Running the docs build on GitHub Actions restores that trust. PRs that do not touch docs or library sources now pass cleanly. PRs that do touch them get a reliable pass/fail signal with enough memory to actually complete the build, so warnings surface where they belong rather than being masked by OOM failures. pre-commit.ci is left to focus on what it is good at, fast lint and format checks, and reviewers and contributors get back the signal they rely on to ship changes confidently. Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/workflows/docs-build.yml | 42 ++++++++++++++++++++++++++++++++ .github/workflows/test.yml | 1 + .pre-commit-config.yaml | 21 ---------------- 3 files changed, 43 insertions(+), 21 deletions(-) create mode 100644 .github/workflows/docs-build.yml diff --git a/.github/workflows/docs-build.yml b/.github/workflows/docs-build.yml new file mode 100644 index 0000000000..ddeee6ba87 --- /dev/null +++ b/.github/workflows/docs-build.yml @@ -0,0 +1,42 @@ +name: Build Sphinx documentation + +on: + push: + branches: [main] + paths: + - "docs/**" + - "cosmos/**" + - ".github/workflows/docs-build.yml" + pull_request: + branches: [main] + paths: + - "docs/**" + - "cosmos/**" + - ".github/workflows/docs-build.yml" + +concurrency: + group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} + cancel-in-progress: true + +jobs: + build: + runs-on: ubuntu-latest + permissions: + contents: read + steps: + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + ref: ${{ github.event.pull_request.head.sha || github.ref }} + persist-credentials: false + + - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0 + with: + python-version: "3.11" + + - name: Install documentation dependencies + run: | + python -m pip install --upgrade pip + pip install -r docs/requirements.txt + + - name: Build Sphinx documentation + run: sphinx-build -b html docs docs/_build --fail-on-warning --fresh-env diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index cd8c6c5556..5b52a1f677 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -85,6 +85,7 @@ jobs: .github/ISSUE_TEMPLATE/*) ;; .github/dependabot.yml) ;; .github/workflows/docs.yml) ;; + .github/workflows/docs-build.yml) ;; .github/workflows/stale.yml) ;; .github/workflows/actionlint.yml) ;; .github/workflows/codeql.yml) ;; diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 3f5a23ae70..7fe603a0f5 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -100,27 +100,6 @@ repos: - id: blacken-docs alias: black additional_dependencies: [black>=26.3.1] - - repo: local - hooks: - - id: check-docs-build - name: Ensure the docs build without errors - entry: sphinx-build -b html docs docs/_build --fail-on-warning --fresh-env - language: python - additional_dependencies: - [ - "aenum", - "deprecation", - "msgpack", - "apache-airflow", - "pydata-sphinx-theme>=0.16.0", - "sphinx", - "sphinx-autoapi", - "sphinx-autobuild", - "sphinx-reredirects", - "sphinxcontrib.mermaid", - ] - pass_filenames: false - files: ^docs/ - repo: https://github.com/pre-commit/mirrors-mypy rev: "v1.20.0" hooks: From 5af6f1cad58d5bec30ab7c766130bc3e2ee82038 Mon Sep 17 00:00:00 2001 From: Pankaj Koti Date: Mon, 20 Apr 2026 13:29:52 +0530 Subject: [PATCH 2/4] TEMP: run docs-build workflow on separate-out-docs-build branch Revert before merging to main. This lets the workflow exercise on a push to this branch so we can confirm the Sphinx build succeeds on GitHub Actions before the fix reaches main. Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/workflows/docs-build.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/docs-build.yml b/.github/workflows/docs-build.yml index ddeee6ba87..6c830e7463 100644 --- a/.github/workflows/docs-build.yml +++ b/.github/workflows/docs-build.yml @@ -1,8 +1,10 @@ name: Build Sphinx documentation on: + # TODO: remove `separate-out-docs-build` before merging; it is only here to + # validate the workflow end-to-end on this branch before the PR is opened. push: - branches: [main] + branches: [main, separate-out-docs-build] paths: - "docs/**" - "cosmos/**" From c24a2807628051d9316cbb6fe0ba7aad128925a8 Mon Sep 17 00:00:00 2001 From: Pankaj Koti Date: Mon, 20 Apr 2026 13:33:48 +0530 Subject: [PATCH 3/4] Update .github/workflows/docs-build.yml --- .github/workflows/docs-build.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs-build.yml b/.github/workflows/docs-build.yml index 6c830e7463..314ad6afff 100644 --- a/.github/workflows/docs-build.yml +++ b/.github/workflows/docs-build.yml @@ -4,7 +4,7 @@ on: # TODO: remove `separate-out-docs-build` before merging; it is only here to # validate the workflow end-to-end on this branch before the PR is opened. push: - branches: [main, separate-out-docs-build] + branches: [main] paths: - "docs/**" - "cosmos/**" From c3d9af7975339813e8181ce36a6494eee37f311d Mon Sep 17 00:00:00 2001 From: Pankaj Koti Date: Mon, 20 Apr 2026 14:23:41 +0530 Subject: [PATCH 4/4] Update .github/workflows/docs-build.yml Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .github/workflows/docs-build.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/docs-build.yml b/.github/workflows/docs-build.yml index 314ad6afff..73690662f3 100644 --- a/.github/workflows/docs-build.yml +++ b/.github/workflows/docs-build.yml @@ -1,8 +1,7 @@ name: Build Sphinx documentation on: - # TODO: remove `separate-out-docs-build` before merging; it is only here to - # validate the workflow end-to-end on this branch before the PR is opened. + # Run this workflow when documentation sources or this workflow definition change. push: branches: [main] paths: