Repository files navigation

GitHub Action to set up thepixi package manager.

-uses:prefix-dev/setup-pixi@v0.8.13with:pixi-version:v0.49.0cache:trueauth-host:prefix.devauth-token:${{ secrets.PREFIX_DEV_TOKEN }}-run:pixi run test

version:2updates:  -package-ecosystem:github-actionsdirectory:/schedule:interval:monthly# or daily, weeklygroups:dependencies:patterns:          -'*'

To see all available input arguments, see theaction.yml file.

The action supports caching of the pixi environment.By default, caching is enabled if apixi.lock file is present.It will then use thepixi.lock file to generate a hash of the environment and cache it.If the cache is hit, the action will skip the installation and use the cached environment.You can specify the behavior by setting thecache input argument.

If you need to customize your cache-key, you can use thecache-key input argument.This will be the prefix of the cache key. The full cache key will be<cache-key><conda-arch>-<hash>.

In order to not exceed the10 GB cache size limit as fast, you might want to restrict when the cache is saved.This can be done by setting thecache-write argument.

-uses:prefix-dev/setup-pixi@v0.8.13with:cache:truecache-write:${{ github.event_name == 'push' && github.ref_name == 'main' }}

With pixi, you can create multiple environments for different requirements.You can also specify which environment(s) you want to install by setting theenvironments input argument.This will install all environments that are specified and cache them.

[project]name ="my-package"channels = ["conda-forge"]platforms = ["linux-64"][dependencies]python =">=3.11"pip ="*"polars =">=0.14.24,<0.21"[feature.py311.dependencies]python ="3.11.*"[feature.py312.dependencies]python ="3.12.*"[environments]py311 = ["py311"]py312 = ["py312"]

The following example will install thepy311 andpy312 environments in different jobs.

test:runs-on:ubuntu-lateststrategy:matrix:environment:[py311, py312]steps:    -uses:actions/checkout@v4    -uses:prefix-dev/setup-pixi@v0.8.13with:environments:${{ matrix.environment }}

The following example will install both thepy311 and thepy312 environment on the runner.

-uses:prefix-dev/setup-pixi@v0.8.13with:# separated by spacesenvironments:>-      py311      py312-run:|    pixi run -e py311 test    pixi run -e py312 test

There are currently three ways to authenticate with pixi:

• using a token
• using a username and password
• using a conda-token
• using an S3 key pair

For more information, see thepixi documentation.

Specify the token using theauth-token input argument.This form of authentication (bearer token in the request headers) is mainly used atprefix.dev.

-uses:prefix-dev/setup-pixi@v0.8.13with:auth-host:prefix.devauth-token:${{ secrets.PREFIX_DEV_TOKEN }}

Specify the username and password using theauth-username andauth-password input arguments.This form of authentication (HTTP Basic Auth) is used in some enterprise environments withartifactory for example.

-uses:prefix-dev/setup-pixi@v0.8.13with:auth-host:custom-artifactory.comauth-username:${{ secrets.PIXI_USERNAME }}auth-password:${{ secrets.PIXI_PASSWORD }}

Specify the conda-token using theauth-conda-token input argument.This form of authentication (token is encoded in URL:https://my-quetz-instance.com/t/<token>/get/custom-channel) is used atanaconda.org or withquetz instances.

-uses:prefix-dev/setup-pixi@v0.8.13with:auth-host:anaconda.org# or my-quetz-instance.comauth-conda-token:${{ secrets.CONDA_TOKEN }}

Specify the S3 key pair using theauth-access-key-id andauth-secret-access-key input arguments.You can also specify the session token using theauth-session-token input argument.

-uses:prefix-dev/setup-pixi@v0.8.13with:auth-host:s3://my-s3-bucketauth-s3-access-key-id:${{ secrets.ACCESS_KEY_ID }}auth-s3-secret-access-key:${{ secrets.SECRET_ACCESS_KEY }}# only needed if your key uses a session tokenauth-s3-session-token:${{ secrets.SESSION_TOKEN }}

See thepixi documentation for more information about S3 authentication.

setup-pixi allows you to run command inside of the pixi environment by specifying a custom shell wrapper withshell: pixi run bash -e {0}.This can be useful if you want to run commands inside of the pixi environment, but don't want to use thepixi run command for each command.

-run:|# everything here will be run inside of the pixi environment    python --version    pip install --no-deps -e .shell:pixi run bash -e {0}

You can even run Python scripts like this:

-run:|# everything here will be run inside of the pixi environment    import my_package    print("Hello world!")shell:pixi run python {0}

If you want to use PowerShell, you need to specify-Command as well.

-run:|# everything here will be run inside of the pixi environment    python --version | Select-String "3.11"shell:pixi run pwsh -Command {0}# pwsh works on all platforms

Withpixi exec, you can also run a one-off command inside a temporary pixi environment.

-run:|# everything here will be run inside of the temporary pixi environment    zstd --versionshell:pixi exec --spec zstd -- bash -e {0}

-run:|# everything here will be run inside of the temporary pixi environment    import ruamel.yaml    # ...shell:pixi exec --spec python=3.11.* --spec ruamel.yaml -- python {0}

Seehere for more information aboutpixi exec.

Instead of using a custom shell wrapper, you can also make all pixi-installed binaries available to subsequent steps by "activating" the installed environment in the currently running job.To this end,setup-pixi adds all environment variables set when executingpixi run to$GITHUB_ENV and, similarly, adds all path modifications to$GITHUB_PATH.As a result, all installed binaries can be accessed without having to callpixi run.

-uses:prefix-dev/setup-pixi@v0.8.13with:activate-environment:true

If you are installing multiple environments, you will need to specify the name of the environment that you want to be activated.

-uses:prefix-dev/setup-pixi@v0.8.13with:environments:>-      py311      py312activate-environment:py311

Activating an environment may be more useful than using a custom shell wrapper as it allows non-shell based steps to access binaries on the path.However, be aware that this option augments the environment of your job.

You can specify whethersetup-pixi should runpixi install --frozen orpixi install --locked depending on thefrozen or thelocked input argument.See theofficial documentation for more information about the--frozen and--locked flags.

-uses:prefix-dev/setup-pixi@v0.8.13with:locked:true# orfrozen:true

If you don't specify anything, the default behavior is to runpixi install --locked if apixi.lock file is present andpixi install otherwise.

There are two types of debug logging that you can enable.

The first one is the debug logging of the action itself.This can be enabled by running the action with theRUNNER_DEBUG environment variable set totrue.

-uses:prefix-dev/setup-pixi@v0.8.13env:RUNNER_DEBUG:true

Alternatively, you can enable debug logging for the action by re-running the action in debug mode:

For more information about debug logging in GitHub Actions, seethe official documentation.

The second type is the debug logging of the pixi executable.This can be specified by setting thelog-level input.

-uses:prefix-dev/setup-pixi@v0.8.13with:# one of `q`, `default`, `v`, `vv`, or `vvv`.log-level:vvv

If nothing is specified,log-level will default todefault orvv depending on ifdebug logging is enabled for the action.

On self-hosted runners, it may happen that some files are persisted between jobs.This can lead to problems or secrets getting leaked between job runs.To avoid this, you can use thepost-cleanup input to specify the post cleanup behavior of the action (i.e., what happensafter all your commands have been executed).

If you setpost-cleanup totrue, the action will delete the following files:

• .pixi environment
• the pixi binary
• the rattler cache
• other rattler files in~/.rattler

If nothing is specified,post-cleanup will default totrue.

On self-hosted runners, you also might want to alter the default pixi install location to a temporary location. You can usepixi-bin-path: ${{ runner.temp }}/bin/pixi to do this.

-uses:prefix-dev/setup-pixi@v0.8.13with:post-cleanup:true# ${{ runner.temp }}\Scripts\pixi.exe on Windowspixi-bin-path:${{ runner.temp }}/bin/pixi

You can also use a preinstalled local version of pixi on the runner by not setting any of thepixi-version,pixi-url orpixi-bin-path inputs. This action will then try to find a local version of pixi in the runner's PATH.

setup-pixi will automatically pick up thepyproject.toml if it contains a[tool.pixi.project] section and nopixi.toml.This can be overwritten by setting themanifest-path input argument.

-uses:prefix-dev/setup-pixi@v0.8.13with:manifest-path:pyproject.toml

If you only want to install pixi and not install the current project, you can use therun-install option.

-uses:prefix-dev/setup-pixi@v0.8.13with:run-install:false

You can also download pixi from a custom URL by setting thepixi-url input argument.Optionally, you can combine this with thepixi-url-bearer-token input argument to authenticate the download request.

-uses:prefix-dev/setup-pixi@v0.8.13with:pixi-url:https://pixi-mirror.example.com/releases/download/v0.48.0/pixi-x86_64-unknown-linux-muslpixi-url-bearer-token:${{ secrets.PIXI_MIRROR_BEARER_TOKEN }}

Thepixi-url input argument can also be aHandlebars template string.It will be rendered with the following variables:

• version: The version of pixi that is being installed (latest or a version likev0.48.0).
• latest: A boolean indicating if the version islatest.
• pixiFile: The name of the pixi binary to download, as determined by the system of the runner (e.g.,pixi-x86_64-unknown-linux-musl).

By default,pixi-url is equivalent to the following template:

-uses:prefix-dev/setup-pixi@v0.8.13with:pixi-url:|      {{#if latest~}}      https://github.com/prefix-dev/pixi/releases/latest/download/{{pixiFile}}      {{~else~}}      https://github.com/prefix-dev/pixi/releases/download/{{version}}/{{pixiFile}}      {{~/if}}

Alternatively to setting the inputs in thewith section, you can also set each of them using environment variables.The corresponding environment variable names are derived from the input names by converting them to uppercase, replacing hyphens with underscores, and prefixing them withSETUP_PIXI_.

For example, thepixi-bin-path input can be set using theSETUP_PIXI_PIXI_BIN_PATH environment variable.

This is particularly useful if executing the action on a self-hosted runner.

Inputs always take precedence over environment variables.

If you want to see more examples, you can take a look at theGitHub Workflows of this repository.

1. Clone this repository.
2. Runpnpm install inside the repository (if you don't havepnpm installed, you can install it withpixi global install pnpm).
3. Runpnpm dev for live transpilation of the TypeScript source code.
4. To test the action, you can runact (inside docker) or use ✨ CI driven development ✨.