Skip to content

Add docs workflow #18

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
alexkorovko wants to merge 1 commit into from
Closed

Add docs workflow #18

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 69 additions & 0 deletions .github/workflows/docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
name: Docs

on:
push:
branches: [main]
paths:
- "docs/**"
- ".github/workflows/docs.yml"
pull_request:
branches: [main]
types: [opened, synchronize, reopened]
paths:
- "docs/**"
- ".github/workflows/docs.yml"
workflow_dispatch:

concurrency:
group: docs-${{ github.ref }}
cancel-in-progress: true

env:
FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true

permissions:
contents: read

jobs:
build:
name: "Build"
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@v5

@coderabbitai coderabbitai Bot Jun 23, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Pin all third-party actions to commit SHAs.

Lines 33, 35, 47, and 69 use tag-based action refs. Pinning to immutable SHAs is required by the stated policy and reduces supply-chain tampering risk.

Proposed change 
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@<full_commit_sha>
...
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@<full_commit_sha>
...
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@<full_commit_sha>
...
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@<full_commit_sha>

Also applies to: 35-35, 47-47, 69-69

🧰 Tools
🪛 zizmor (1.26.1)

[warning] 33-33: credential persistence through GitHub Actions artifacts (artipacked): does not set persist-credentials: false

(artipacked)

[error] 33-33: unpinned action reference (unpinned-uses): action is not pinned to a hash (required by blanket policy)

(unpinned-uses)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/docs.yml at line 33, Replace all tag-based action
references with immutable commit SHAs to reduce supply-chain tampering risk. The
actions/checkout action at line 33 and other third-party actions at lines 35,
47, and 69 are currently using version tags (like `@v5`) instead of commit SHAs.
For each of these action references, replace the tag with the specific commit
SHA (e.g., @{full-40-character-SHA}) to ensure the exact version is pinned and
prevent unexpected changes from tag updates.

Source: Linters/SAST tools

🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Harden checkout by disabling credential persistence.

actions/checkout currently leaves credentials available to later steps; set persist-credentials: false unless push operations are required.

Proposed change 
       - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
- uses: actions/checkout@v5
- uses: actions/checkout@v5
with:
persist-credentials: false
🧰 Tools
🪛 zizmor (1.26.1)

[warning] 33-33: credential persistence through GitHub Actions artifacts (artipacked): does not set persist-credentials: false

(artipacked)

[error] 33-33: unpinned action reference (unpinned-uses): action is not pinned to a hash (required by blanket policy)

(unpinned-uses)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/docs.yml at line 33, The actions/checkout step at line 33
is leaving credentials available to later workflow steps, which is a security
risk. Add the `persist-credentials: false` option to the actions/checkout@v5
action configuration to disable credential persistence, ensuring credentials are
not available to subsequent steps unless explicitly needed for push operations.

Source: Linters/SAST tools


- uses: actions/setup-python@v5
with:
python-version: "3.11"

- name: Install dependencies
run: pip install -r docs/sphinx/requirements.txt

- name: Build HTML docs
run: python -m sphinx -b html -W --keep-going docs/sphinx docs/build
Comment on lines +39 to +43

@coderabbitai coderabbitai Bot Jun 23, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Move inline build/install commands into repo scripts.

Line 40 and Line 43 execute build logic inline in YAML, which violates the workflow path rule and makes CI behavior harder to reuse/version.

Proposed change 
-      - name: Install dependencies
-        run: pip install -r docs/sphinx/requirements.txt
-
-      - name: Build HTML docs
-        run: python -m sphinx -b html -W --keep-going docs/sphinx docs/build
+      - name: Build HTML docs
+        run: ./docs/build_docs_ci.sh

As per path instructions, "Build and test commands must not appear inline in YAML; they should call scripts."

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/docs.yml around lines 39 - 43, The pip install and sphinx
build commands are currently executed inline in the YAML workflow. Extract these
commands from the run steps "Install dependencies" and "Build HTML docs" into
separate shell scripts in the repository (for example, under a scripts
directory), then update the corresponding run steps to call those scripts
instead of executing the commands directly in YAML. This ensures build and test
logic is versioned with the repository and follows the workflow path rule.

Source: Path instructions


- name: Upload Pages artifact
if: github.event_name != 'pull_request'
uses: actions/upload-pages-artifact@v3
with:
path: docs/build

deploy:
name: "Deploy"
needs: build
if: github.event_name != 'pull_request'
runs-on: ubuntu-latest
timeout-minutes: 15

permissions:
pages: write
id-token: write

environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}

steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
Loading