[pydantic-ai] GitHub Actions uv 캐시에 cache-suffix 도입 — 패키지셋별 격리

PR 링크: pydantic/pydantic-ai#3282 상태: Merged | 변경: +22 / -6

들어가며

Pydantic AI의 CI는 lint, mypy, docs, test(all-extras), test(lowest-versions) 등 다양한 작업을 실행하며, 각 작업이 설치하는 패키지 조합이 다릅니다. 모든 작업이 동일한 uv 캐시 키를 사용하면, 한 작업이 저장한 캐시가 다른 작업에 의해 덮어쓰여져 캐시 적중률이 떨어집니다. 이 PR은 각 작업에 고유한 cache-suffix를 부여하여 캐시를 격리합니다.

핵심 코드 분석

Before (ci.yml):

- uses: astral-sh/setup-uv@v5
  with:
    enable-cache: true

env:
  UV_PYTHON: ${{ matrix.python-version }}

After:

- uses: astral-sh/setup-uv@v5
  with:
    python-version: ${{ matrix.python-version }}
    enable-cache: true
    cache-suffix: ${{ matrix.install.name }}  # lint, mypy, docs, all-extras 등

주요 변경 사항:

1. cache-suffix 추가: lint, mypy, docs, live, all-extras, lowest-versions, dev, docs-upload, deploy-docs-preview, smokeshow 등 작업별 고유 접미사 부여
2. UV_PYTHON을 python-version으로 대체: 환경변수 대신 setup-uv의 python-version 파라미터를 직접 사용하여 캐시 키에 Python 버전이 자동 포함

왜 이게 좋은가

• 작업별 캐시 격리로 캐시 적중률이 크게 향상됩니다. uv sync --all-extras의 캐시와 uv sync --group lint의 캐시가 서로 간섭하지 않습니다.
• UV_PYTHON 환경변수 제거로, Python 버전이 setup-uv 한 곳에서만 관리됩니다.
• GitHub Actions 캐시 키가 setup-uv-{os}-{python-version}-{cache-suffix}-{lock-hash} 형태로 명확해집니다.

정리

• CI 캐시는 작업 단위로 격리하라: 패키지 조합이 다른 작업이 같은 캐시를 공유하면 cache thrashing이 발생합니다.
• 설정은 한 곳에서 관리하라: UV_PYTHON 환경변수와 python-version 파라미터를 이중으로 쓰면 불일치 위험이 있습니다.

참고 자료

• pydantic/pydantic-ai#3282 — PR 전체 diff
• astral-sh/setup-uv cache-suffix 문서 — cache-suffix 설정

⚠️ 알림: 이 분석은 AI가 실제 코드 diff를 기반으로 작성했습니다.