跳转到内容

在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 creates a separate mountpoint for the build directory,
  # so we need to copy instead of using hard links.
  UV_LINK_MODE: copy

uv:
  image: ghcr.io/astral-sh/uv:$UV_VERSION-python$PYTHON_VERSION-$BASE_LAYER
  script:
    # your `uv` commands

注意

如果您使用的是无发行版镜像，必须指定入口点： 

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:
    # Your `uv` commands
    - uv cache prune --ci

有关配置缓存的更多详情，请参阅GitLab缓存文档。

建议在任务结束时使用uv cache prune --ci来减小缓存大小。更多详情请参阅uv缓存文档。

使用 uv pip

如果使用uv pip接口而非uv项目接口，uv默认需要一个虚拟环境。若要允许将包安装到系统环境中，请在所有uv调用中使用--system标志或设置UV_SYSTEM_PYTHON变量。

UV_SYSTEM_PYTHON 变量可以在不同作用域中定义。您可以在此处详细了解GitLab中变量及其优先级的工作原理

通过在顶层定义整个工作流来选择加入：

gitlab-ci.yml
variables:
  UV_SYSTEM_PYTHON: 1

# [...]

要再次选择退出，可以在任何uv调用中使用--no-system标志。

在持久化缓存时，您可能希望使用requirements.txt或pyproject.toml作为缓存键文件，而不是uv.lock。