byteforce

CPN 한국어 자습서 · 외부 문서 한국어 미러

UV 문서 · Guides

GitHub Actions에서 uv 사용하기

Using uv in GitHub Actions · 원문: docs.astral.sh/uv/guides/integration/github/

아래는 원문을 한국어로 옮긴 미러입니다. 코드·명령은 원문 그대로이며, 가장 최신 정보는 하단 원문 링크에서 확인하세요.

설치

GitHub Actions에서는 공식 astral-sh/setup-uv 액션 사용을 권장합니다. 이 액션은 설치, PATH 구성, 선택적 캐시 유지를 처리하며 uv와 호환되는 모든 플랫폼을 지원합니다.

최신 버전을 설치하려면 다음을 사용합니다:

코드 · 명령
name: Example

jobs:
  uv-example:
    name: python
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v6

      - name: Install uv
        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0

특정 버전에 고정하는 것이 모범 사례입니다:

코드 · 명령
- name: Install uv
  uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
  with:
    # Install a specific version of uv.
    version: "0.11.24"

Python 설정하기

프로젝트에서 고정된 버전을 사용하는 uv python install로 Python을 설치할 수 있습니다:

코드 · 명령
- name: Set up Python
  run: uv python install

또는 공식 GitHub setup-python 액션은 캐시된 버전을 통해 더 빠른 실행을 제공합니다. 프로젝트에 고정된 버전을 사용하도록 설정합니다:

코드 · 명령
- name: "Set up Python"
  uses: actions/setup-python@v6
  with:
    python-version-file: ".python-version"

- name: Install uv
  uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0

또는 pyproject.toml을 사용하여 고정 버전을 무시하고 최신 호환 버전을 사용합니다:

코드 · 명령
- name: "Set up Python"
  uses: actions/setup-python@v6
  with:
    python-version-file: "pyproject.toml"

여러 Python 버전 테스트하기

여러 Python 버전에 걸쳐 매트릭스 테스트를 수행하려면 setup-uv를 통해 버전을 설정합니다:

코드 · 명령
jobs:
  build:
    name: continuous-integration
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version:
          - "3.10"
          - "3.11"
          - "3.12"

    steps:
      - uses: actions/checkout@v6

      - name: Install uv and set the Python version
        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
        with:
          python-version: ${{ matrix.python-version }}

setup-uv 액션 없이는 UV_PYTHON 환경변수를 사용합니다:

코드 · 명령
jobs:
  build:
    name: continuous-integration
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version:
          - "3.10"
          - "3.11"
          - "3.12"
    env:
      UV_PYTHON: ${{ matrix.python-version }}
    steps:
      - uses: actions/checkout@v6

동기화 및 실행

uv와 Python 설정 후 uv sync로 프로젝트를 설치하고 uv run을 통해 명령을 실행합니다:

코드 · 명령
name: Example

jobs:
  uv-example:
    name: python
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v6

      - name: Install uv
        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0

      - name: Install the project
        run: uv sync --locked --all-extras --dev

      - name: Run tests
        # For example, using `pytest`
        run: uv run pytest tests

참고: UV_PROJECT_ENVIRONMENT 설정을 사용하면 가상환경을 생성하는 대신 시스템 Python 환경에 설치할 수 있습니다.

캐싱

워크플로우 실행 간에 uv의 캐시 디렉터리를 캐싱하면 CI 시간을 단축할 수 있습니다.

astral-sh/setup-uv 액션에는 내장 캐시 지원이 포함되어 있습니다:

코드 · 명령
- name: Enable caching
  uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
  with:
    enable-cache: true

actions/cache를 사용한 수동 캐시 관리:

코드 · 명령
jobs:
  install_job:
    env:
      # Configure a constant location for the uv cache
      UV_CACHE_DIR: /tmp/.uv-cache

    steps:
      # ... setup up Python and uv ...

      - name: Restore uv cache
        uses: actions/cache@v5
        with:
          path: /tmp/.uv-cache
          key: uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
          restore-keys: |
            uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
            uv-${{ runner.os }}

      # ... install packages, run tests, etc ...

      - name: Minimize uv cache
        run: uv cache prune --ci

uv cache prune --ci 명령은 CI 환경에서 캐시 크기를 줄입니다. uv pip를 사용할 때는 캐시 키에서 uv.lock 대신 requirements.txt를 사용합니다.

비일시적 자체 호스팅 러너의 경우, GitHub 워크스페이스 내에 캐시를 배치하고 사후 작업 훅을 사용하여 작업 완료 후 제거하는 것을 권장합니다:

코드 · 명령
install_job:
  env:
    # Configure a relative location for the uv cache
    UV_CACHE_DIR: ${{ github.workspace }}/.cache/uv

이를 위해 ACTIONS_RUNNER_HOOK_JOB_STARTED 환경변수를 정리 스크립트로 설정해야 합니다:

코드 · 명령
#!/usr/bin/env sh
uv cache clean

uv pip 사용하기

프로젝트 인터페이스 대신 uv pip를 사용할 때, uv는 기본적으로 가상환경을 필요로 합니다. 시스템 환경에 설치하려면 --system 플래그를 사용하거나 UV_SYSTEM_PYTHON을 설정합니다.

워크플로우 전체에서 활성화:

코드 · 명령
env:
  UV_SYSTEM_PYTHON: 1

jobs: ...

특정 작업에서 활성화:

코드 · 명령
jobs:
  install_job:
    env:
      UV_SYSTEM_PYTHON: 1
    ...

특정 단계에서 활성화:

코드 · 명령
steps:
  - name: Install requirements
    run: uv pip install -r requirements.txt
    env:
      UV_SYSTEM_PYTHON: 1

이 동작을 비활성화하려면 --no-system 플래그를 사용합니다.

프라이빗 저장소

프라이빗 GitHub 저장소의 의존성이 있는 프로젝트의 경우, uv가 가져올 수 있도록 읽기 권한이 있는 개인 액세스 토큰(PAT)을 설정합니다.

PAT를 생성하고 저장소 시크릿(예: MY_PAT)으로 추가한 후, gh CLI를 사용하여 Git 자격증명을 설정합니다:

코드 · 명령
steps:
  - name: Register the personal access token
    run: echo "${{ secrets.MY_PAT }}" | gh auth login --with-token
  - name: Configure the Git credential helper
    run: gh auth setup-git

PyPI에 게시하기

uv는 신뢰할 수 있는 게시(자격증명 설정 불필요)를 사용하는 릴리스 워크플로우로 PyPI에 패키지를 빌드하고 게시할 수 있습니다.

릴리스 워크플로우 예시:

코드 · 명령
name: "Publish release to PyPI"

on:
  push:
    tags:
      # Publish on any tag starting with a `v`, e.g., v0.1.0
      - v*

jobs:
  run:
    runs-on: ubuntu-latest
    environment:
      name: pypi
    permissions:
      id-token: write
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@v6
      - name: Install uv
        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
      - name: Install Python 3.13
        run: uv python install 3.13
      - name: Build
        run: uv build
      # Check that basic features work and we didn't miss to include crucial files
      - name: Smoke test (wheel)
        run: uv run --isolated --no-project --with dist/*.whl tests/smoke_test.py
      - name: Smoke test (source distribution)
        run: uv run --isolated --no-project --with dist/*.tar.gz tests/smoke_test.py
      - name: Publish
        run: uv publish

설정 단계:

  1. 저장소 설정의 Settings → Environments에서 "pypi" 환경 생성
  2. PyPI 프로젝트 설정의 "Publishing" 아래에 신뢰할 수 있는 게시자 추가 — 모든 필드가 GitHub 설정과 일치하는지 확인
  3. 릴리스에 태그를 달고(v로 시작) 푸시:
코드 · 명령
$ git tag -a v0.1.0 -m v0.1.0
$ git push --tags

원문(영어): https://docs.astral.sh/uv/guides/integration/github/ · 본 문서는 학습용 한국어 번역이며 원본의 권리는 원저작자(Astral)에게 있습니다.

원문(영어): https://docs.astral.sh/uv/guides/integration/github/