setup-python-action

Install Python on Forgejo Actions runners and cache pip/pipenv/poetry through fjord/cache-action. A port of actions/setup-python that does not rely on the GitHub-hosted runner toolcache or GitHub Releases. Composite action, pure shell, no build step.

Python is provisioned with uv, which downloads python-build-standalone builds, resolves version specs, reuses a local install directory across jobs, and honors a configurable mirror. uv must be available on the runner (bake it into your runner image, or install it once).

Quick start

jobs:
  test:
    runs-on: [self-hosted, Linux]
    env:
      RASTER_CACHE_S3_BUCKET: ci-cache
      RASTER_CACHE_S3_ENDPOINT: https://fsn1.your-objectstorage.com
      RASTER_CACHE_S3_REGION: fsn1
      RASTER_CACHE_S3_ACCESS_KEY_ID: ${{ secrets.CACHE_S3_KEY_ID }}
      RASTER_CACHE_S3_SECRET_ACCESS_KEY: ${{ secrets.CACHE_S3_SECRET }}
    steps:
      - uses: actions/checkout@v6
      - uses: https://rasterhub.com/fjord/setup-python-action@v1
        with:
          python-version: '3.12'
          cache: pip
      - run: pip install -r requirements.txt
      - run: pytest

Inputs

Mirror actions/setup-python.

Input	Default	Description
python-version		Exact (3.12.3), major.minor (3.12), or PyPy (pypy3.10).
python-version-file		Path to a version file (.python-version). Auto-detected.
architecture	runner arch	Accepted; uv selects the build for the runner.
cache		pip, pipenv, or poetry. Empty disables caching.
cache-dependency-path	manager default	Dependency file(s) to hash, one per line.
python-mirror	uv default	python-build-standalone mirror (UV_PYTHON_INSTALL_MIRROR) for air-gapped / github-independent runners.

Outputs

Output	Description
python-version	Resolved version installed.
python-path	Absolute path to the interpreter.
cache-hit	Exact cache match (empty when cache is disabled).

How it works

• Install: uv python install <spec> into a persistent dir ($RUNNER_TOOL_CACHE/uv-python, reused across jobs), then exposes python / python3 on PATH via a small shim. CPython by default; PyPy specs work where uv supports them. No GitHub API, no github-hosted toolcache layout.
• Mirror: set python-mirror to point uv at your own python-build-standalone mirror so installs never reach github.com.
• Cache: when cache: is set, a step resolves the manager's cache directory and a dependency-hash key, then a nested fjord/cache-action step restores it and saves it in the job post step. Needs a configured cache backend (RASTER_CACHE_*).

Examples

See examples/workflows: pip, poetry, uv, and tox.

Notes

• uv is required for the install step. If it is missing, the action fails with an actionable message. This is the deliberate, github.com-independent path.
• Complex version constraints beyond exact / major.minor / PyPy are delegated to uv's own resolution.

License

MIT. See LICENSE.