Skip to content

GitLab CI/CD에서 uv 사용하기

uv 이미지 사용하기

Astral은 uv가 사전 설치된 Docker 이미지를 제공한다. 여러분의 워크플로우에 적합한 버전을 선택한다.

gitlab-ci.yml
variables:
  UV_VERSION: 0.5
  PYTHON_VERSION: 3.12
  BASE_LAYER: bookworm-slim
  # GitLab CI는 빌드 디렉토리에 별도의 마운트 포인트를 생성하므로
  # 하드 링크 대신 복사를 사용해야 한다.
  UV_LINK_MODE: copy

uv:
  image: ghcr.io/astral-sh/uv:$UV_VERSION-python$PYTHON_VERSION-$BASE_LAYER
  script:
    # `uv` 커맨드

Note

distroless 이미지를 사용하는 경우, 엔트리포인트를 지정해야 한다: 

uv:
  image:
    name: ghcr.io/astral-sh/uv:$UV_VERSION
    entrypoint: [""]
  # ...

캐싱

워크플로 실행 간에 uv 캐시를 유지하면 성능을 향상시킬 수 있다.

uv-install:
  variables:
    UV_CACHE_DIR: .uv-cache
  cache:
    - key:
        files:
          - uv.lock
      paths:
        - $UV_CACHE_DIR
  script:
    # `uv` 커맨드
    - uv cache prune --ci

캐싱 설정에 대한 자세한 내용은 GitLab 캐싱 문서를 참고한다.

작업이 끝날 때 uv cache prune --ci를 사용해 캐시 크기를 줄이는 것이 좋다. 자세한 내용은 uv 캐시 문서를 확인한다.

uv pip 사용하기

uv 프로젝트 인터페이스 대신 uv pip 인터페이스를 사용할 때, uv는 기본적으로 가상 환경을 요구한다. 시스템 환경에 패키지를 설치하려면 모든 uv 실행 시 --system 플래그를 사용하거나 UV_SYSTEM_PYTHON 변수를 설정한다.

UV_SYSTEM_PYTHON 변수는 다양한 범위에서 정의할 수 있다. GitLab에서 변수와 그 우선순위가 어떻게 작동하는지에 대해 더 알아볼 수 있다.

전체 워크플로우에 대해 옵트인하려면 최상위 레벨에서 변수를 정의한다:

gitlab-ci.yml
variables:
  UV_SYSTEM_PYTHON: 1

# [...]

다시 옵트아웃하려면 uv 실행 시 --no-system 플래그를 사용한다.

캐시를 유지할 때 uv.lock 대신 requirements.txt나 pyproject.toml을 캐시 키 파일로 사용할 수 있다.