Auto-deploy docs to GitHub Pages on push to main

[vitali87]

Summary

• New workflow that builds and deploys mkdocs to GitHub Pages on push to main
• Only triggers when docs/, mkdocs.yml, or source code changes
• Uses official GitHub Pages actions (upload-pages-artifact + deploy-pages)

Test plan

• Enable GitHub Pages (Settings → Pages → Source: GitHub Actions) after merge
• Verify docs deploy on next push to main

[gemini-code-assist]

Note

Gemini is unable to generate a summary for this pull request due to the file types involved not being currently supported.

[greptile-apps]

Greptile Summary

This PR adds a GitHub Actions workflow (.github/workflows/docs.yml) that automatically builds and deploys MkDocs documentation to GitHub Pages on every push to main that touches docs/, mkdocs.yml, or src/speculant_graph/. The workflow is split into two jobs — build and deploy — following GitHub's recommended Pages deployment pattern.

All three concerns raised in previous review rounds have been addressed:

• workflow_dispatch is now present, enabling manual first-time deployment.
• Dependencies now use uv sync --no-dev --extra docs, dropping dev tooling from the install.
• Permissions are correctly scoped per-job: the build job inherits the workflow-level contents: read, while only the deploy job holds pages: write and id-token: write.

One contextual note: torch, transformers, accelerate, and datasets are still installed because they are core project dependencies (not dev extras), and mkdocstrings with show_source: true must import the modules to generate API docs — so the current install command is the minimum viable approach given the project's architecture.

Confidence Score: 5/5

Safe to merge — all previously raised P1 concerns have been addressed and no new issues were found.

The three issues flagged in earlier rounds (missing workflow_dispatch, overly broad permissions, heavy dev deps) have all been resolved. No new logic, security, or correctness issues were identified. The heavy core dependency install (torch, etc.) is unavoidable given show_source: true in mkdocs.yml requires module imports, and was already discussed. The workflow follows GitHub's recommended Pages deployment pattern with correctly scoped permissions.

No files require special attention.

Important Files Changed

Filename	Overview
.github/workflows/docs.yml	New GitHub Actions workflow that builds and deploys MkDocs to GitHub Pages on push to main; previously raised concerns about permissions, workflow_dispatch, and heavy deps have been addressed.

Sequence Diagram

sequenceDiagram
    participant GH as GitHub (push to main)
    participant Build as build job (contents: read)
    participant UV as uv / mkdocs
    participant Artifact as Pages Artifact Store
    participant Deploy as deploy job (pages: write, id-token: write)
    participant Pages as GitHub Pages

    GH->>Build: Trigger (docs/**, mkdocs.yml, src/speculant_graph/**, or workflow_dispatch)
    Build->>UV: uv sync --no-dev --extra docs
    UV-->>Build: mkdocs + mkdocstrings + core deps installed
    Build->>UV: uv run mkdocs build --strict
    UV-->>Build: site/ directory generated
    Build->>Artifact: upload-pages-artifact (site/)
    Artifact-->>Build: Artifact stored
    Build-->>Deploy: needs: build satisfied
    Deploy->>Artifact: Fetch github-pages artifact
    Deploy->>Pages: deploy-pages (OIDC token)
    Pages-->>Deploy: Deployment URL

Loading

_{Reviews (4): Last reviewed commit: "ci: scope permissions per-job and skip d..." | Re-trigger Greptile}

[vitali87]

@greptile

[vitali87]

@greptile

[vitali87]

@greptile