Fix docs build failure by ensuring stable SCM versioning in CI workflow

[srivatsankrishnan]

Summary

Fix docs build failure caused by SCM version mismatch during uv sync. This PR also fixes the bugs in the orignal CI/CD when using uv as a default way to use CloudAI. For instance, PR 701 and PR 702 makes the first version to upload the uv lock file.

This PR also fixes the bug introduced by PR 684 where deploys the CI flow for building and publishing the GH document but does not introduce necessary checks to ensure the uv.lock file is pushed everytime the python package dependencies are modified and developer uses uv to run.

Root cause

The failing step was building/installing cloudai itself during the docs workflow’s uv sync.

• cloudai uses SCM-based dynamic versioning (pdm-backend + source = "scm").

• In CI, the repo was checked out in a way that could be shallow / missing full git history/tags, which makes SCM-version computation flaky.

• Under that condition, the build backend can produce inconsistent versions between wheel filename and wheel metadata, leading to:
  --metadata version: 0.1.dev…+g
  --wheel filename version: 0.1.dev…+g.dYYYYMMDD

Tools reject this as an invalid wheel (“metadata version does not match wheel filename”), so the docs job fails during “Set up envir

Test Plan

• CI/CD
• Manual Github action workflow (fork)

Additional Notes

Keeping the pytest with pip based flow since we also support pip as described in the documentation.

[coderabbitai]

📝 Walkthrough

Walkthrough

The GitHub Actions CI workflow was updated to use the UV package manager for dependency installation and task runs, reference the Python version from a file, enable UV caching, and add a lock-file verification step.

Changes

Cohort / File(s)	Summary
CI Workflow .github/workflows/ci.yml	Checkout now uses fetch-depth: 0; Python setup reads version from .python-version; installs UV (astral-sh/setup-uv v5) with cache; adds uv lock --check; replaces pip install '.[dev,docs]' with uv sync --frozen --extra dev --extra docs; replaces individual linters/build commands with uv run ... invocations (ruff, pyright, vulture, lint-imports, taplo, make html).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

I nibble at the CI log, nose in a flurry,
UV sync hums softly—no need to hurry,
Locks are checked, linters run with cheer,
A tidy workflow, hop-hop, bring it near! 🐇✨

Pre-merge checks

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main objective: fixing a docs build failure by ensuring stable SCM versioning, which directly relates to the changeset's core modifications in the CI workflow.
Description check	✅ Passed	The PR description clearly explains the root cause of the docs build failure, details the SCM versioning mismatch issue, and describes the changes made to fix it in the CI workflow.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[amaslenn]

This PR adds a workaround addressing symptoms, not the root cause. The real issue is that #760 didn't update uv.lock file.

Please add the following command to avoid such issues in future: uv lock --check (right after "Install dependencies" step under "lint" job).

@srivatsankrishnan please do not create new PRs for the same topic as you did with (#756 and #760), that ruins review process.

[srivatsankrishnan]

This PR adds a workaround addressing symptoms, not the root cause. The real issue is that #760 didn't update uv.lock file.

Please add the following command to avoid such issues in future: uv lock --check (right after "Install dependencies" step under "lint" job).

@srivatsankrishnan please do not create new PRs for the same topic as you did with (#756 and #760), that ruins review process.

The CI/CD you added (pivot towards uv) is buggy @amaslenn. The root cause is a mismatch time stamp getting generated as clearly described in the PR description.

Ideally you are right that this (uv lock --check) should have been added to the original CI/CD flow when we pivoted to uv first flow. Not adding lock file is a trigger and not the cause. I do understand the purpose of uv.lock file. Also its weird that the documentation build is not part of the PR CI/CD but happening outside of it. Ideally it should have been part of it as well.

[greptile-apps]

Greptile Summary

Fixed docs build failure by adding fetch-depth: 0 to checkout step in CI workflow, ensuring full git history is available for SCM-based versioning (pdm-backend). This prevents version mismatches between wheel metadata and filename. Also migrated lint job from pip to uv package manager and added uv.lock validation check.

Key Changes:

• Added fetch-depth: 0 to lint job's checkout step - fixes SCM versioning issue that caused docs build to fail
• Migrated lint job to use uv instead of pip (uv sync --frozen, uv run for all commands)
• Added uv.lock --check step to enforce lock file is kept up to date
• Added python-version-file: ".python-version" for consistent Python version
• Updated uv.lock with aiconfigurator~=0.4.0 dependency and version updates

Issues Found:

• Test job still uses pip throughout while lint job now uses uv, creating inconsistency in the CI workflow
• All pytest commands, cloudai commands, and pip operations in test job should be migrated to use uv run prefix or uv pip for consistency
• The partial migration leaves the codebase in an inconsistent state where some jobs use uv and others use pip

Confidence Score: 3/5

• Safe to merge with minor inconsistencies - fixes critical docs build issue but leaves test job using pip
• The core fix (fetch-depth: 0) correctly addresses the SCM versioning issue that caused docs build failures. However, the PR incompletely migrates to uv - the lint job uses uv while the test job continues using pip, creating workflow inconsistency. This won't cause failures but represents technical debt.
• .github/workflows/ci.yml - test job still uses pip instead of uv, creating inconsistency with lint job

Important Files Changed

Filename	Overview
.github/workflows/ci.yml	Migrated lint job from pip to uv, added fetch-depth: 0 for SCM versioning, added uv.lock validation check; test job still uses pip inconsistently
uv.lock	Added aiconfigurator dependency and updated package versions including pydantic constraint; standard lockfile update

Sequence Diagram

sequenceDiagram
    participant GH as GitHub Actions
    participant Repo as Repository
    participant UV as uv Package Manager
    participant Build as pdm-backend (SCM)
    participant Docs as Sphinx Docs

    Note over GH,Docs: Lint Job (Fixed)
    GH->>Repo: Checkout with fetch-depth: 0
    Note right of Repo: Full git history<br/>for SCM versioning
    GH->>GH: Setup Python from .python-version
    GH->>UV: Install uv with cache enabled
    UV->>Repo: Check uv.lock is up to date
    Note right of Repo: Validates lock file<br/>matches dependencies
    UV->>UV: sync --frozen --extra dev --extra docs
    UV->>Build: Build cloudai package
    Build->>Repo: Read git tags/history (SCM)
    Note right of Build: Stable version:<br/>0.1.dev+g<sha>
    Build-->>UV: Package built successfully
    UV->>GH: Run linters (ruff, pyright, vulture)
    UV->>Docs: Build documentation (make html)
    Note right of Docs: Uses stable version<br/>from SCM

    Note over GH,Docs: Test Job (Still uses pip)
    GH->>Repo: Checkout with fetch-depth: 0
    GH->>GH: Setup Python (matrix: 3.10, 3.12)
    GH->>GH: pip install '.[dev]'
    Note right of GH: Inconsistent with<br/>lint job's uv usage
    GH->>GH: Run pytest suite
    GH->>GH: Test local installation (pip)
    GH->>GH: Test cloudai commands

Loading

[greptile-apps]

Additional Comments (1)

1. .github/workflows/ci.yml, line 24-33 (link)

   style: uv is installed and lockfile is checked, but dependencies are still installed via pip on line 30. Consider using uv sync --frozen --extra dev --extra docs for consistency with the docs workflow and deterministic builds

   _{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

_{2 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[coderabbitai]

Actionable comments posted: 2

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a28b3dc and b11e939.

📒 Files selected for processing (1)

• .github/workflows/ci.yml

🔇 Additional comments (3)

.github/workflows/ci.yml (3)

16-17: LGTM! Full git checkout enables stable SCM versioning.

This change correctly addresses the root cause described in the PR: shallow checkouts were causing flaky SCM-version computation, leading to version mismatches between wheel metadata and filename.

---

21-22: LGTM! Pinning to .python-version ensures consistency.

Reading the Python version from .python-version ensures the lint job uses the repository's standard Python version, improving consistency across environments.

---

32-33: LGTM! Lock file validation prevents drift.

This step correctly implements the requested uv lock --check validation immediately after dependency installation, as specified in the PR comments. It ensures uv.lock remains synchronized with pyproject.toml, preventing the lock file drift that contributed to the versioning issues.

[greptile-apps]

Additional Comments (2)

1. .github/workflows/ci.yml, line 29-30 (link)

   style: The lint job uses pip install while the docs workflow uses uv sync --frozen. Consider using uv sync --frozen --all-extras here too for consistency and to ensure deterministic builds matching uv.lock.

   _{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

2. .github/workflows/ci.yml, line 86-87 (link)

   style: Test job uses pip install instead of uv sync. Consider using uv sync --frozen for deterministic builds matching the lockfile.

   _{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

_{2 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Additional Comments (3)

1. .github/workflows/ci.yml, line 14-17 (link)

   logic: PR description claims to fix docs build workflow, but these SCM versioning fixes are applied to ci.yml (PR checks) instead of .github/workflows/docs.yml (main branch documentation deployment). The docs workflow still lacks fetch-depth: 0 needed for stable SCM versioning.

2. .github/workflows/ci.yml, line 32-33 (link)

   logic: The uv lock --check validation runs after pip install '.[dev,docs]' on line 30. If dependencies changed, pip install may fail before the lock check can detect it. Consider moving this check before the pip install step, or switch to using uv sync --frozen instead of pip.

   _{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

3. .github/workflows/ci.yml, line 76-79 (link)

   style: The test job also adds fetch-depth: 0 but doesn't install uv or check uv.lock consistency. For consistency with the lint job, consider adding the same uv setup and lock validation here.

   _{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

_{1 file reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Additional Comments (1)

1. .github/workflows/ci.yml, line 76-87 (link)

   logic: test job still uses pip instead of uv, inconsistent with the PR's stated goal to "fix bugs in the original CI/CD when using uv as a default way to use CloudAI"

   _{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between b11e939 and 303ef98.

⛔ Files ignored due to path filters (1)

• uv.lock is excluded by !**/*.lock

📒 Files selected for processing (1)

• .github/workflows/ci.yml

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: Greptile Review
• GitHub Check: Run pytest (3.10)
• GitHub Check: Run pytest (3.12)

🔇 Additional comments (4)

.github/workflows/ci.yml (4)

16-17: LGTM: Full git checkout enables stable SCM versioning.

The fetch-depth: 0 ensures the full git history (tags, commits) is available, which is necessary for SCM-based dynamic versioning to compute consistent versions.

---

21-22: LGTM: Using version file ensures consistency.

Reading the Python version from .python-version ensures the CI environment matches the repository's pinned version.

---

24-27: LGTM: UV installation with caching configured.

The UV package manager is properly installed with caching enabled for improved CI performance.

---

29-30: LGTM: Lock file verification addresses maintainer feedback.

The uv lock --check step validates that uv.lock is synchronized with pyproject.toml before dependency installation, catching drift early. This directly addresses the maintainer's request in the comments.

[greptile-apps]

Additional Comments (6)

1. .github/workflows/ci.yml, line 76-79 (link)

   style: test job still uses pip while lint job now uses uv, creating inconsistency. Should migrate test job to uv as well for consistency.

   _{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

2. .github/workflows/ci.yml, line 86-87 (link)

   style: test job still uses pip instead of uv. Should use uv sync --frozen --extra dev for consistency with lint job.

   _{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

3. .github/workflows/ci.yml, line 89-102 (link)

   style: test job should use uv run prefix for pytest commands to match lint job's pattern.

   _{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

4. .github/workflows/ci.yml, line 104-111 (link)

   style: Local installation test still uses pip. Consider migrating to uv for consistency, or document why pip is required here.

   _{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

5. .github/workflows/ci.yml, line 113-114 (link)

   style: cloudai commands should use uv run prefix for consistency with the lint job pattern.

   _{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

6. .github/workflows/ci.yml, line 120-132 (link)

   style: cloudai commands should use uv run prefix for consistency.

   _{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

_{1 file reviewed, 6 comments}

_{Edit Code Review Agent Settings | Greptile}

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

.github/workflows/ci.yml (1)

86-87: Consider migrating test job to uv for consistency.

The test job still uses pip install while the lint job now uses uv sync --frozen. This creates an inconsistency where the two jobs may resolve different dependency versions:

• Lint job: Uses exact versions from uv.lock
• Test job: Resolves dependencies at runtime from pyproject.toml constraints

For consistency and to ensure both jobs test against the same locked dependencies, consider migrating to:

uv sync --frozen --extra dev

Trade-off consideration: If the intent is to validate that pip-based installation (as documented for users) still works, then keeping pip install has value. However, this should be documented, and you might want a separate job that explicitly tests pip installation while the main test job uses uv for reproducibility.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 303ef98 and dc9288f.

📒 Files selected for processing (1)

• .github/workflows/ci.yml

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: Greptile Review
• GitHub Check: Run pytest (3.10)
• GitHub Check: Run pytest (3.12)

🔇 Additional comments (5)

.github/workflows/ci.yml (5)

16-17: Correct fix for SCM versioning.

Setting fetch-depth: 0 ensures the full git history and tags are available, which is essential for pdm-backend's SCM-based dynamic versioning to compute stable, consistent versions. This directly addresses the root cause described in the PR objectives.

---

29-30: Good addition per PR requirements.

The uv lock --check step addresses the concern raised in the PR comments about catching missing or outdated lock files in CI. Positioning this check before uv sync ensures fast failure if the lock file is out of date, preventing inconsistent dependency resolution.

---

33-33: Correctly includes --frozen flag.

The uv sync --frozen --extra dev --extra docs command now strictly enforces the locked dependencies from uv.lock, addressing the critical issue from the previous review. This ensures reproducible builds and prevents dependency drift.

---

36-63: Consistent use of uv run for all commands.

All linter and documentation build commands now execute via uv run, ensuring they use the uv-managed environment with locked dependencies. The preservation of PYTHONPATH=src on line 48 for lint-imports is correct and necessary.

---

21-22: The .python-version file exists and contains the valid Python version 3.10, so the workflow configuration is correct.

[srivatsankrishnan]

Additional Comments (6)

1. .github/workflows/ci.yml, line 76-79 (link)
   style: test job still uses pip while lint job now uses uv, creating inconsistency. Should migrate test job to uv as well for consistency.
   Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
2. .github/workflows/ci.yml, line 86-87 (link)
   style: test job still uses pip instead of uv. Should use uv sync --frozen --extra dev for consistency with lint job.
   Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
3. .github/workflows/ci.yml, line 89-102 (link)
   style: test job should use uv run prefix for pytest commands to match lint job's pattern.
   Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
4. .github/workflows/ci.yml, line 104-111 (link)
   style: Local installation test still uses pip. Consider migrating to uv for consistency, or document why pip is required here.
   Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
5. .github/workflows/ci.yml, line 113-114 (link)
   style: cloudai commands should use uv run prefix for consistency with the lint job pattern.
   Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
6. .github/workflows/ci.yml, line 120-132 (link)
   style: cloudai commands should use uv run prefix for consistency.
   Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

1 file reviewed, 6 comments

Edit Code Review Agent Settings | Greptile

@greptile
Added details in the PR. Better to also have some pip based flows since we support that as well.

[greptile-apps]

Got it! I've created a rule to remember that CloudAI intentionally uses mixed pip/uv workflows in CI to ensure compatibility with both package managers. Future reviews won't flag this as an inconsistency.

This approach makes a lot of sense - it gives you confidence that CloudAI works correctly regardless of which installation method users choose, and it's good practice for a project that officially supports multiple package managers.

[amaslenn]

Since you've also migrated to uv, setting up python separately is not needed, uv sync will do it automatically.

[amaslenn]

Why the whole history is needed for this job?

[srivatsankrishnan]

Andrei will provide the fix to the CI bug.