2.7.5 在 GitLab CI/CD 中使用

  1分钟内可阅读完  

原文链接: https://docs.astral.sh/uv/guides/integration/gitlab/

2.7.5 在 GitLab CI/CD 中使用

使用 uv 镜像

Astral 提供了预装 uv 的 Docker 镜像。请选择适合你工作流的变体。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# .gitlab-ci.yml
variables:
  UV_VERSION: "0.12.19"
  PYTHON_VERSION: "3.12"
  BASE_LAYER: trixie-slim
  # GitLab CI 会为构建目录创建单独的挂载点，
  # 所以我们需要复制而不是使用硬链接。
  UV_LINK_MODE: copy

uv:
  image: ghcr.io/astral-sh/uv:$UV_VERSION-python$PYTHON_VERSION-$BASE_LAYER
  script:
    # 你的 `uv` 命令

注意

如果你使用 distroless 镜像，则必须指定 entrypoint：

1
2
3
4
5

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

缓存

在多次工作流运行之间持久化 uv 缓存可以提升性能。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

uv-install:
  variables:
    UV_CACHE_DIR: .uv-cache
  cache:
    - key:
        files:
          - uv.lock
      paths:
        - $UV_CACHE_DIR
  script:
    # 你的 `uv` 命令
  after_script:
    - 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 中变量及其优先级的更多内容可以在这里阅读。

在顶层定义即可对整个工作流启用：

1
2
3
4
5

# .gitlab-ci.yml
variables:
  UV_SYSTEM_PYTHON: 1

# [...]

要重新关闭该行为，可以在任意 uv 调用中使用 --no-system 标志。

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

最后修改 September 25, 2026: 更新 (221c74c33)