CI/CD pipelines

GitLab CI/CD

For GitLab CI/CD pipelines there are various Docker images with pre-installed uv: Available images.

.gitlab-ci.yml
 1variables:
 2  UV_VERSION: 0.4
 3  PYTHON_VERSION: 3.12
 4  BASE_LAYER: bookworm-slim
 5
 6
 7stages:
 8  - build
 9
10uv-install:
11  stage: build
12  image: ghcr.io/astral-sh/uv:$UV_VERSION-python$PYTHON_VERSION-$BASE_LAYER
13  variables:
14    UV_CACHE_DIR: .uv-cache
15  cache:
16    - key:
17        files:
18          - uv.lock
19      paths:
20        - $UV_CACHE_DIR
21  script:
22    # YOUR UV COMMANDS
23    - uv cache prune --ci
Line 23

This reduces the cache size, see also Caching in continuous integration.

See also

GitHub Actions

The official astral-sh/setup-uv GitHub action installs uv, adds it to PATH and provides a cache for the installed packages:

ci.yml
name: ci

jobs:
  test:
    name: python
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v3
        with:
          version: "0.4.24"

You can then install either a single Python version or a matrix with uv:

ci.yml
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
         python-version-file: "pyproject.toml"

or

ci.yml
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
         python-version-file: ".python-version"

or

ci.yml
name: ci

strategy:
  matrix:
    python-version:
      - "3.9"
      - "3.10"
      - "3.11"
      - "3.12"
      - "3.13"

jobs:
  test:
    name: python
    # ...
      - name: Set up Python ${{ matrix.python-version }}
        run: uv python install ${{ matrix.python-version }}

See also

uv sync and uv run

Once uv and Python are installed, the project can be installed with uv sync and commands can be executed in the environment with uv run, for example for pytest:

ci.yml
      - name: Install the project
        run: uv sync --all-extras --dev

      - name: Run tests
        run: uv run pytest tests

Caching

The uv cache improves runtimes:

ci.yml
      - name: Enable caching
        uses: astral-sh/setup-uv@v3
        with:
          enable-cache: true

Invalidates the cache if uv.lock changes:

ci.yml
      - name: Define a cache dependency glob
        uses: astral-sh/setup-uv@v3
        with:
          enable-cache: true
          cache-dependency-glob: "uv.lock"