Skip to content

fix(ci): pin the uv toolchain deterministically - #114

Merged
seonghobae merged 9 commits into
mainfrom
fix/pin-uv-toolchain
Aug 11, 2026
Merged

fix(ci): pin the uv toolchain deterministically#114
seonghobae merged 9 commits into
mainfrom
fix/pin-uv-toolchain

Conversation

@seonghobae

@seonghobae seonghobae commented Aug 10, 2026

Copy link
Copy Markdown
Contributor

RCA

Protected-main CI pins the astral-sh/setup-uv action by immutable commit but did not pin the uv executable version. With no root uv.toml/required-version and no explicit workflow version, setup-uv logged that it was falling back to latest and resolved uv 0.12.3 at execution time. The same reviewed source could therefore execute dependency locking, environment materialization, and package builds under a different uv release merely because time passed.

The smallest non-conflicting remedy is a repository-root exact uv requirement. Official setup-uv behavior discovers required-version from root uv.toml after checkout when no explicit workflow version overrides it, and uv itself enforces the same PEP 440 requirement.

Test-first remediation

  1. RED toolchain contract be1e314f362471b15b8acb66a3ba208cdcf220c7 added tests/test_uv_toolchain_pin.py. CI 31414909820 failed exactly because root uv.toml was absent (1 failed, 350 passed, 3 deselected on the observed Python 3.10 job). The setup log independently showed the missing config, latest fallback, and installation of uv 0.12.3.
  2. GREEN root fix de19a02207695af65707ad23914401ef0efec21c added only uv.toml with required-version = "==0.12.3". CI 31415048033, Security Scan 31415047789, and SAST 31415047871 all succeeded. The quality log showed setup-uv finding 0.12.3 in root uv.toml, then installing exactly that version; Python 3.10/3.12/3.14, 100% owned production statement/branch coverage, 100% public docstrings, Ruff, lock freshness, package builds, Compose, and both container builds passed.
  3. RED doctoring contract a83d547c6466f5762b591c659b0e583d98d4cff8 added tests/test_uv_toolchain_documentation.py. CI 31415255835 failed exactly because docs/doctoring/uv-toolchain-reproducibility.md did not yet exist (1 failed, 351 passed, 3 deselected on Python 3.14).
  4. GREEN documentation closure current source 5c8996a2c21eee3c3cccc1d2a0afe9b2d2f1dbbe adds the bounded doctoring record with the immutable-action/executable/lock evidence separation, reviewed update procedure, rollback path, Python 3.14 preservation, and APA 7 primary references. CI 31415422810, Security Scan 31415422788, and SAST 31415422726 are all completed / success.

Current exact state

  • Source head: 5c8996a2c21eee3c3cccc1d2a0afe9b2d2f1dbbe.
  • Independently resolved protected main: bf2cc2e140dc3ff4a56c3203f80f41bb9fed5d10.
  • GitHub reports Draft and mergeable.
  • Changed scope is four disjoint files: root uv.toml, two toolchain contract tests, and one doctoring record.
  • Formal reviews: none. Unresolved inline review threads: zero at the fresh pre-write refetch.
  • The current PR workflow still checked out GitHub's synthetic pull-request merge revision, so these successful runs are staged integration evidence, not protected exact-source acceptance.

Scope and dependency boundary

This slice does not edit .github/workflows/ci.yml, pyproject.toml, package source, schema, provider behavior, credentials, uv.lock, release publication, or any stacked product branch. It does not change runtime dependencies or package version. The shared CHANGELOG is intentionally not churned from this branch while multiple active implementation stacks own that integration surface; the doctoring record is the bounded design/recovery authority for this unintegrated tooling slice.

Repository exact-source governance #88 remains the only repository-local prerequisite before this branch can rely on PR workflow evidence as exact contributor-head acceptance. Current live organization rules require the central workflow set and review-thread resolution on the default branch, but required_approving_review_count is 0, code-owner review is disabled, and last-push approval is not required. Therefore absence of an independent formal approval is not a current merge blocker for this leaf unless live policy changes before merge.

ContextualWisdomLab/.github#790 remains a read-only central change and must not be copied, weakened, triggered, dismissed, resolved, or merged by this repository writer. Its historical review state is not promoted into an extra leaf approval requirement beyond the current live ruleset. Required central workflow results on this PR must instead be evaluated directly on the unchanged final head after #88 reaches protected main.

Primary references

Doctoring records APA 7 references to Astral's official setup-uv version-configuration guidance, uv GitHub Actions guidance, and the uv required-version setting.

Merge boundary

Keep Draft until #88 reaches protected main. Then revalidate this unchanged final source against the new protected exact-source contract and the live organization ruleset. Merge only when every required central/repository CI, security, coverage, package, provenance, and release gate is terminal-success, zero valid unresolved findings remain, review threads are resolved, and any approval requirement that live policy actually imposes at that time is satisfied. No predecessor, generated-merge-only, queued, pending, cancelled, skipped, stale, status-only, author-only, infrastructure-only, or failed evidence transfers.

Summary by CodeRabbit

  • 개선 사항

    • Python 도구체인 버전을 0.12.3으로 고정해 개발 및 자동화 환경의 일관성을 높였습니다.
    • CI 환경에서도 고정된 도구체인을 사용하도록 검증을 강화했습니다.
  • 문서

    • 버전 고정의 배경, 운영 범위와 보안 고려사항을 문서화했습니다.
    • 업데이트 및 롤백 절차와 검증 범위를 기록했습니다.
  • 테스트

    • 도구체인 버전 고정과 CI 설정을 검증하는 회귀 테스트를 추가했습니다.
    • 관련 문서의 존재 여부와 필수 내용을 확인합니다.

@coderabbitai

coderabbitai Bot commented Aug 10, 2026

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 27a6f633-c4d5-4c89-a207-aa38ed0e621b

📥 Commits

Reviewing files that changed from the base of the PR and between fa54fd6 and e67f46e.

📒 Files selected for processing (1)
  • tests/test_uv_toolchain_pin.py
🚧 Files skipped from review as they are similar to previous changes (1)
  • tests/test_uv_toolchain_pin.py

📝 Walkthrough

Walkthrough

저장소의 uv 버전을 0.12.3으로 고정했습니다. CI 설정 검증 테스트와 도구체인 재현성 문서를 추가했습니다. 문서는 업데이트·롤백 절차와 보안·공급망 고려사항을 기록합니다.

Changes

uv 도구체인 재현성

Layer / File(s) Summary
uv 버전 고정 및 CI 검증
uv.toml, tests/test_uv_toolchain_pin.py
required-version = "==0.12.3"을 설정했습니다. CI의 setup-uv 단계 수, 버전 재정의 여부, 허용된 작업 디렉터리를 검증합니다.
재현성 운영 문서와 검증
docs/doctoring/uv-toolchain-reproducibility.md, tests/test_uv_toolchain_documentation.py
버전 고정의 배경, 테스트 근거, 업데이트·롤백 절차, 보안 및 공급망 고려사항을 문서화했습니다. 필수 문구의 존재를 검증합니다.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed 제목은 CI에서 uv 도구체인을 결정적으로 고정하는 변경 사항을 정확하고 간결하게 설명합니다.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch fix/pin-uv-toolchain

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

Comment @coderabbitai help to get the list of available commands.

@seonghobae
seonghobae marked this pull request as ready for review August 11, 2026 20:24

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Actionable comments posted: 1

🧹 Nitpick comments (1)
tests/test_uv_toolchain_documentation.py (1)

11-27: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

문서 절차의 내용을 검증하도록 테스트를 강화하세요.

현재 테스트는 키워드가 한 번 나타나는지만 확인합니다. 제목만 남기거나 부정문으로 rollback을 언급해도 테스트가 통과할 수 있습니다.

정확한 required-version 문장과 update procedure, rollback and recovery 섹션을 확인하세요. uv.toml 삭제 또는 latest 선택을 금지하는 핵심 문장도 검증하세요.

핵심 문장 검증 예시
     normalized = " ".join(DOCTORING.read_text(encoding="utf-8").lower().split())
 
+    assert 'required-version = "==0.12.3"' in normalized
+    assert "## update procedure" in normalized
+    assert "## rollback and recovery" in normalized
+    assert "do not recover by deleting" in normalized
+
     for phrase in (
🤖 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 `@tests/test_uv_toolchain_documentation.py` around lines 11 - 27, Strengthen
test_uv_toolchain_doctoring_records_reproducibility_and_recovery to assert the
exact required-version statement and the distinct “update procedure” and
“rollback and recovery” sections, rather than checking isolated keywords. Also
assert the documentation explicitly prohibits deleting uv.toml and choosing
latest, so negated or title-only mentions cannot satisfy the test.
🤖 Prompt for all review comments with 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.

Inline comments:
In `@tests/test_uv_toolchain_pin.py`:
- Around line 25-30: Update
test_ci_uses_setup_uv_without_an_explicit_latest_override to inspect each
setup-uv workflow step individually, including the prune-cache step, and assert
that neither version nor version-file is configured. If a setup-uv step has
working-directory, require it to reference only the repository root, while
ignoring version: latest settings in unrelated workflow steps.

---

Nitpick comments:
In `@tests/test_uv_toolchain_documentation.py`:
- Around line 11-27: Strengthen
test_uv_toolchain_doctoring_records_reproducibility_and_recovery to assert the
exact required-version statement and the distinct “update procedure” and
“rollback and recovery” sections, rather than checking isolated keywords. Also
assert the documentation explicitly prohibits deleting uv.toml and choosing
latest, so negated or title-only mentions cannot satisfy the test.
🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: a053b888-f4a5-4e7d-a9a5-a9c3e72694ff

📥 Commits

Reviewing files that changed from the base of the PR and between 545334a and 1bfe7d2.

📒 Files selected for processing (4)
  • docs/doctoring/uv-toolchain-reproducibility.md
  • tests/test_uv_toolchain_documentation.py
  • tests/test_uv_toolchain_pin.py
  • uv.toml

Comment thread tests/test_uv_toolchain_pin.py Outdated

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🧹 Nitpick comments (1)
tests/test_uv_toolchain_pin.py (1)

12-12: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

- uses: 형식도 처리하도록 보강하세요.

_setup_uv_step_blocks는 현재 uses: 이전의 - name 줄을 찾아야 단계로 인식합니다. - uses: astral-sh/setup-uv@... 형식에서는 이 탐색이 실패하여 AssertionError가 발생합니다. uses:- 로 시작하면 step_start = uses_index를 사용하세요.

🤖 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 `@tests/test_uv_toolchain_pin.py` at line 12, Update _setup_uv_step_blocks to
recognize setup-uv steps written directly as “- uses:” by setting step_start to
uses_index when the uses line begins with “- ”; retain the existing “- name”
lookup for named steps and preserve the current assertion behavior for
unsupported formats.

Source: MCP tools

🤖 Prompt for all review comments with 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.

Nitpick comments:
In `@tests/test_uv_toolchain_pin.py`:
- Line 12: Update _setup_uv_step_blocks to recognize setup-uv steps written
directly as “- uses:” by setting step_start to uses_index when the uses line
begins with “- ”; retain the existing “- name” lookup for named steps and
preserve the current assertion behavior for unsupported formats.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 1dda10d4-8271-40dc-803d-61098eb61582

📥 Commits

Reviewing files that changed from the base of the PR and between 1bfe7d2 and fa54fd6.

📒 Files selected for processing (2)
  • tests/test_uv_toolchain_documentation.py
  • tests/test_uv_toolchain_pin.py
🚧 Files skipped from review as they are similar to previous changes (1)
  • tests/test_uv_toolchain_documentation.py

@seonghobae
seonghobae merged commit 06f88be into main Aug 11, 2026
33 checks passed
@seonghobae
seonghobae deleted the fix/pin-uv-toolchain branch August 11, 2026 22:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant