Skip to content

python-dependency-manager.md

Latest commit

 

History

History
153 lines (112 loc) · 3.89 KB

python-dependency-manager.md

File metadata and controls

153 lines (112 loc) · 3.89 KB

forge-ci-python-tools-dependency-manager

Install and cache Python dependencies for poetry/uv/venv projects.

Usage

jobs:
  dependencies:
    uses: whisller/forge-ci/.github/workflows/forge-ci-python-tools-dependency-manager.yml@v1
    with:
      python-version: '3.12'
      dependency-manager: 'poetry'

Inputs

Input Type Required Default Description
python-version string No '3.12' Python version to use
working-directory string No '.' Working directory for dependency operations
dependency-manager string No 'poetry' Dependency manager: poetry, uv, or venv
poetry-version string No '2.2.0' Poetry version (if using poetry)
uv-version string No '0.8' uv version (if using uv)
runs-on string No 'ubuntu-latest' Runner to use

Outputs

Output Type Description
dependencies-cache-key string Cache key for installed dependencies

Behavior

  1. Check Cache: Looks for existing cached dependencies
  2. Install Manager: Installs poetry/uv via pip if needed (venv is built-in)
  3. Install Dependencies: Installs project dependencies into .venv/ directory
  4. Cache Dependencies: Saves .venv/ with composite cache key
  5. Output Cache Key: Provides key for downstream jobs to restore cache

Cache Key Format

python-deps-{manager}-{os}-{python-version}-{lock-file-hash}

Example: python-deps-poetry-ubuntu-latest-3.12-a1b2c3d4

Examples

Basic Poetry Project

jobs:
  dependencies:
    uses: whisller/forge-ci/.github/workflows/forge-ci-python-tools-dependency-manager.yml@v1

uv with Python 3.11

jobs:
  dependencies:
    uses: whisller/forge-ci/.github/workflows/forge-ci-python-tools-dependency-manager.yml@v1
    with:
      python-version: '3.11'
      dependency-manager: 'uv'

Monorepo with Working Directory

jobs:
  dependencies:
    uses: whisller/forge-ci/.github/workflows/forge-ci-python-tools-dependency-manager.yml@v1
    with:
      working-directory: 'services/api'
      dependency-manager: 'poetry'

Using Cache Key in Downstream Jobs

jobs:
  dependencies:
    uses: whisller/forge-ci/.github/workflows/forge-ci-python-tools-dependency-manager.yml@v1

  lint:
    needs: dependencies
    uses: whisller/forge-ci/.github/workflows/forge-ci-python-tools-ruff.yml@v1
    with:
      dependencies-cache-key: ${{ needs.dependencies.outputs.dependencies-cache-key }}

Requirements

Poetry Projects

  • pyproject.toml must exist
  • poetry.lock must exist and be up to date

uv Projects

  • pyproject.toml must exist
  • uv.lock must exist

venv Projects

  • requirements.txt or requirements-dev.txt must exist

Performance

  • Cache Hit: ~10-20 seconds (restore cached .venv)
  • Cache Miss: ~1-3 minutes (full dependency installation)
  • Cache Invalidation: Automatically invalidates when lock files change

Troubleshooting

Cache Miss Every Time

Problem: Dependencies reinstall on every run.

Causes:

  • Lock file changes between runs
  • Different Python version
  • Different runner OS

Solution: Ensure lock files are committed and up to date.

Poetry Lock File Out of Date

Problem: poetry.lock is out of sync with pyproject.toml.

Solution:

poetry lock --no-update
git add poetry.lock
git commit -m "chore: update poetry.lock"

uv Sync Fails

Problem: uv sync fails with "dependency resolution error".

Solution: Update uv.lock:

uv lock
git add uv.lock
git commit -m "chore: update uv.lock"

See Also