feat: Allow caching global environment(s) (#226)

Author: olivier-lacroix

README.md

@@ -23,7 +23,7 @@ GitHub Action to set up the [pixi](https://github.com/prefix-dev/pixi) package m
 ## Usage
 
 ```yml
-- uses: prefix-dev/[email protected].1
+- uses: prefix-dev/[email protected].2
   with:
     pixi-version: v0.49.0
 
@@ -35,7 +35,7 @@ GitHub Action to set up the [pixi](https://github.com/prefix-dev/pixi) package m
 
 > [!WARNING]
 > Since pixi is not yet stable, the API of this action may change between minor versions.
-> Please pin the versions of this action to a specific version (i.e., `prefix-dev/[email protected].1`) to avoid breaking changes.
+> Please pin the versions of this action to a specific version (i.e., `prefix-dev/[email protected].2`) to avoid breaking changes.
 > You can automatically update the version of this action by using [Dependabot](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot).
 >
 > Put the following in your `.github/dependabot.yml` file to enable Dependabot for your GitHub Actions:
@@ -59,22 +59,25 @@ To see all available input arguments, see the [`action.yml`](action.yml) file.
 
 ### Caching
 
-The action supports caching of the pixi environment.
-By default, caching is enabled if a `pixi.lock` file is present.
+The action supports caching of the project and global pixi environments.
+By default, project environment caching is enabled if a `pixi.lock` file is present.
 It will then use the `pixi.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 the `cache` input argument.
 
-If you need to customize your cache-key, you can use the `cache-key` input argument.
-This will be the prefix of the cache key. The full cache key will be `<cache-key><conda-arch>-<hash>`.
+Global environment caching is disabled by default and can be enabled by setting the `global-cache` input to `true`.
+As there is no lockfile for global environments, the cache will expire at the end of every month to ensure it does not go stale.
+
+If you need to customize your cache-key, you can use the `cache-key` and `global-cache-key` input arguments.
+These will be the prefixes of the cache keys. The full cache keys will be `<cache-key><conda-arch>-<hash>` and `<global-cache-key><conda-arch>-<YYYY-MM>-<hash>` respectively.
 
 #### Only save caches on `main`
 
 In order to not exceed the [10 GB cache size limit](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy) as fast, you might want to restrict when the cache is saved.
 This can be done by setting the `cache-write` argument.
 
 ```yml
-- uses: prefix-dev/[email protected].1
+- uses: prefix-dev/[email protected].2
   with:
     cache: true
     cache-write: ${{ github.event_name == 'push' && github.ref_name == 'main' }}
@@ -119,7 +122,7 @@ test:
       environment: [py311, py312]
   steps:
     - uses: actions/checkout@v4
-    - uses: prefix-dev/[email protected].1
+    - uses: prefix-dev/[email protected].2
       with:
         environments: ${{ matrix.environment }}
 ```
@@ -129,7 +132,7 @@ test:
 The following example will install both the `py311` and the `py312` environment on the runner.
 
 ```yml
-- uses: prefix-dev/[email protected].1
+- uses: prefix-dev/[email protected].2
   with:
     # separated by spaces
     environments: >-
@@ -149,10 +152,10 @@ You can specify `pixi global install` commands by setting the `global-environmen
 This will create one environment per line, and install them.
 This is useful in particular to install executables that are needed for `pixi install` to work properly.
 For instance, the `keyring`, or `gcloud` executables. The following example shows how to install both in separate global environments.
-Note that global environments are not cached.
+By default, global environments are not cached. You can enable caching by setting the `global-cache` input to `true`.
 
 ```yml
-- uses: prefix-dev/[email protected].1
+- uses: prefix-dev/[email protected].2
   with:
     global-environments: |
       google-cloud-sdk
@@ -185,7 +188,7 @@ Specify the token using the `auth-token` input argument.
 This form of authentication (bearer token in the request headers) is mainly used at [prefix.dev](https://prefix.dev).
 
 ```yml
-- uses: prefix-dev/[email protected].1
+- uses: prefix-dev/[email protected].2
   with:
     auth-host: prefix.dev
     auth-token: ${{ secrets.PREFIX_DEV_TOKEN }}
@@ -197,7 +200,7 @@ Specify the username and password using the `auth-username` and `auth-password`
 This form of authentication (HTTP Basic Auth) is used in some enterprise environments with [artifactory](https://jfrog.com/artifactory) for example.
 
 ```yml
-- uses: prefix-dev/[email protected].1
+- uses: prefix-dev/[email protected].2
   with:
     auth-host: custom-artifactory.com
     auth-username: ${{ secrets.PIXI_USERNAME }}
@@ -210,7 +213,7 @@ Specify the conda-token using the `auth-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 at [anaconda.org](https://anaconda.org) or with [quetz instances](https://github.com/mamba-org/quetz).
 
 ```yml
-- uses: prefix-dev/[email protected].1
+- uses: prefix-dev/[email protected].2
   with:
     auth-host: anaconda.org # or my-quetz-instance.com
     auth-conda-token: ${{ secrets.CONDA_TOKEN }}
@@ -222,7 +225,7 @@ Specify the S3 key pair using the `auth-access-key-id` and `auth-secret-access-k
 You can also specify the session token using the `auth-session-token` input argument.
 
 ```yaml
-- uses: prefix-dev/[email protected].1
+- uses: prefix-dev/[email protected].2
   with:
     auth-host: s3://my-s3-bucket
     auth-s3-access-key-id: ${{ secrets.ACCESS_KEY_ID }}
@@ -238,7 +241,7 @@ See the [pixi documentation](https://pixi.sh/latest/advanced/s3) for more inform
 You can specify whether to use keyring to look up credentials for PyPI.
 
 ```yml
-- uses: prefix-dev/[email protected].1
+- uses: prefix-dev/[email protected].2
   with:
     pypi-keyring-provider: subprocess # one of 'subprocess', 'disabled'
 ```
@@ -306,15 +309,15 @@ To this end, `setup-pixi` adds all environment variables set when executing `pix
 As a result, all installed binaries can be accessed without having to call `pixi run`.
 
 ```yml
-- uses: prefix-dev/[email protected].1
+- uses: prefix-dev/[email protected].2
   with:
     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.
 
 ```yml
-- uses: prefix-dev/[email protected].1
+- uses: prefix-dev/[email protected].2
   with:
     environments: >-
       py311
@@ -331,7 +334,7 @@ You can specify whether `setup-pixi` should run `pixi install --frozen` or `pixi
 See the [official documentation](https://prefix.dev/docs/pixi/cli#install) for more information about the `--frozen` and `--locked` flags.
 
 ```yml
-- uses: prefix-dev/[email protected].1
+- uses: prefix-dev/[email protected].2
   with:
     locked: true
     # or
@@ -350,7 +353,7 @@ The first one is the debug logging of the action itself.
 This can be enabled by running the action with the `RUNNER_DEBUG` environment variable set to `true`.
 
 ```yml
-- uses: prefix-dev/[email protected].1
+- uses: prefix-dev/[email protected].2
   env:
     RUNNER_DEBUG: true
 ```
@@ -368,7 +371,7 @@ The second type is the debug logging of the pixi executable.
 This can be specified by setting the `log-level` input.
 
 ```yml
-- uses: prefix-dev/[email protected].1
+- uses: prefix-dev/[email protected].2
   with:
     # one of `q`, `default`, `v`, `vv`, or `vvv`.
     log-level: vvv
@@ -394,7 +397,7 @@ If nothing is specified, `post-cleanup` will default to `true`.
 On self-hosted runners, you also might want to alter the default pixi install location to a temporary location. You can use `pixi-bin-path: ${{ runner.temp }}/bin/pixi` to do this.
 
 ```yml
-- uses: prefix-dev/[email protected].1
+- uses: prefix-dev/[email protected].2
   with:
     post-cleanup: true
     # ${{ runner.temp }}\Scripts\pixi.exe on Windows
@@ -410,7 +413,7 @@ You can also use a preinstalled local version of pixi on the runner by not setti
 This can be overwritten by setting the `manifest-path` input argument.
 
 ```yml
-- uses: prefix-dev/[email protected].1
+- uses: prefix-dev/[email protected].2
   with:
     manifest-path: pyproject.toml
 ```
@@ -420,7 +423,7 @@ This can be overwritten by setting the `manifest-path` input argument.
 If you only want to install pixi and not install the current project, you can use the `run-install` option.
 
 ```yml
-- uses: prefix-dev/[email protected].1
+- uses: prefix-dev/[email protected].2
   with:
     run-install: false
 ```
@@ -431,7 +434,7 @@ You can also download pixi from a custom URL by setting the `pixi-url` input arg
 Optionally, you can combine this with the `pixi-url-headers` input argument to supply additional headers for the download request, such as a bearer token.
 
 ```yml
-- uses: prefix-dev/[email protected].1
+- uses: prefix-dev/[email protected].2
   with:
     pixi-url: https://pixi-mirror.example.com/releases/download/v0.48.0/pixi-x86_64-unknown-linux-musl
     pixi-url-headers: '{"Authorization": "Bearer ${{ secrets.PIXI_MIRROR_BEARER_TOKEN }}"}'
@@ -447,7 +450,7 @@ It will be rendered with the following variables:
 By default, `pixi-url` is equivalent to the following template:
 
 ```yml
-- uses: prefix-dev/[email protected].1
+- uses: prefix-dev/[email protected].2
   with:
     pixi-url: |
       {{#if latest~}}

action.yml

@@ -37,13 +37,21 @@ inputs:
     description: Whether to use `pixi install --frozen`. Defaults to `false`.
   cache:
     description: Whether to cache the pixi environment. Defaults to `true`. Only works if `pixi.lock` is present.
+  global-cache:
+    description: |
+      Whether to cache the global environment(s). Defaults to `false`. As there is no lockfile for global environment,
+      the global cache will expire at the end of every month, to ensure it does not go stale.
   cache-key:
     description: |
       Cache key prefix to use for caching the pixi environment.
       Defaults to `pixi-`. The full cache key is `<cache-key><conda-arch>-<sha-256-of-pixi-lock>`.
+  global-cache-key:
+    description: |
+      Cache key prefix to use for caching the global environments.
+      Defaults to `pixi-global-`. The full cache key is `<global-cache-key><conda-arch>-<sha-256-of-global-environments>`.
   cache-write:
     description: |
-      Whether to write to the cache or only read from it. Defaults to `true`.
+      Whether to write to the cache or only read from it. Defaults to `true`. Applies to both project and global caches as the case may be.
   pixi-bin-path:
     description: |
       Path to the pixi binary to use. Defaults to `~/.pixi/bin/pixi`.