setup-micromamba

GitHub Action to set up the micromamba package manager.

Also useful to download micromamba and create conda environments in npm scripts.

Usage

- uses: mamba-org/setup-micromamba@v1
  with:
    micromamba-version: '1.3.1-0'
    environment-file: environment.yml
    init-shell: >-
      bash
      powershell
    cache-environment: true
    post-cleanup: 'all'
- name: Import numpy in micromamba environment (bash)
  run: python -c "import numpy"
  shell: bash -el {0}
- name: Import numpy in micromamba environment (pwsh)
  run: python -c "import numpy"
  shell: pwsh
- name: Run custom command in micromamba environment
  run: pytest --version
  shell: micromamba-shell {0}

Features

To see all available input arguments, see the action.yml file.

Environment creation

setup-micromamba allows you to create micromamba environments from an environment file or from a list of packages. You can use either environment-file or create-args arguments to specify an environment to be created. An environment name (other than base) must also be specified either in the environment file or via environment-name. If the environment is not fully specified then setup-micromamba will skip the environment creation and install only the micromamba executable.

After the environment has been created, setup-micromamba will write micromamba activate <env-name> into the rc file of all shells that are initialized. This will automatically activate the environment when the shell is started.

Create environment from environment file

- uses: mamba-org/setup-micromamba@v1
  with:
    environment-file: environment.yml

Create environment from conda-lock file

Micromamba supports the conda-lock unified lockfile format, but this format does not specify an environment name. Because setup-micromamba requires an environment name to be specified, config might look like this:

- uses: mamba-org/setup-micromamba@v1
  with:
    environment-file: conda-lock.yml
    environment-name: ci

[!NOTE] Beware that micromamba does not allow additional packages to be installed into a locked environment and will ignore additional specs added by create-args, see mamba#1760.

Create environment from environment specs

You can specify extra environment specs using the create-args input.

- uses: mamba-org/setup-micromamba@v1
  with:
    # the create command looks like this:
    # `micromamba create -n test-env python=3.10 numpy`
    environment-name: test-env
    create-args: >-
      python=3.10
      numpy

Custom arguments

You can specify custom arguments for the micromamba create command using the create-args input. See micromamba create --help for more information.

[!NOTE] This is the same argument as in the previous example but with different semantics. This is because internally, setup-micromamba uses the micromamba create command to create the environment from the environment file and there, extra specs are specified by adding them as extra arguments to the micromamba create command.

- uses: mamba-org/setup-micromamba@v1
  with:
    environment-file: environment.yml
    create-args: -v

Shell initialization

In order to be able to activate micromamba environments, you need to initialize your shell. setup-micromamba can create shell initialization scripts for different shells (by calling micromamba shell init -s <shell>). By default, it will create shell initialization scripts for bash. If you want to customize this, you can use the init-shell input.

- uses: mamba-org/setup-micromamba@v1
  with:
    init-shell: bash

In case you don't want to initialize your shell, you can set init-shell to none.

You can also specify multiple shells by separating them with a space (or using the >- YAML block scalar)

- uses: mamba-org/setup-micromamba@v1
  with:
    init-shell: >-
      bash
      powershell
    # or
    init-shell: bash powershell

Please read about login shells for more information about the shell initialization.

Custom micromamba-shell wrapper

setup-micromamba will allow you to run commands in the created micromamba environment with a custom shell wrapper. In this “shell”, the micromamba is activated and the commands are executed. With this, you don't need to initialize your shell and activate the environment which may come in handy for self-hosted runners that persist between jobs. You can set this behavior by specifying the generate-run-shell input (defaults to true).

[!NOTE] Under the hood, this shell wrapper runs micromamba run -r <root-prefix-path> -n <env-name> <command> with <command> being a file containing the part that you specify in the run: section of your workflow. See the official documentation and ADR 0277 for more information about how the shell: input works in GitHub Actions.

[!WARNING] Only available on macOS and Linux.

- uses: mamba-org/setup-micromamba@v1
  with:
    generate-run-shell: true
    environment-file: environment.yml
- run: |
    pytest --version
    pytest
  shell: micromamba-shell {0}

Custom .condarc file

To specify custom channels or other micromamba settings, you may want to use .condarc files to do this.

setup-micromamba allows you to specify a custom .condarc file using either the condarc-file or the condarc input.

When you specify condarc-file, setup-micromamba will use this file for all micromamba commands.

When you specify condarc, setup-micromamba will create a .condarc next to the micromamba binary (to not mess with the ~/.condarc that may be overwritten on self-hosted runners) and use this file for all micromamba commands. The action will also set the CONDARC environment variable to point to this file.

If nothing is specified, setup-micromamba will create a .condarc next to the micromamba binary with conda-forge as the only channel.

- uses: mamba-org/setup-micromamba@v1
  with:
    environment-file: environment.yml
    condarc-file: /path/to/.condarc

- uses: mamba-org/setup-micromamba@v1
  with:
    environment-file: environment.yml
    condarc: |
      channels:
        - my-custom-channel
        - conda-forge
        - pytorch

Caching

If you want to cache your micromamba environment or packages, you can do this by setting the cache-environment (or cache-environment-key) or cache-downloads (or cache-downloads-key) inputs.

If cache-environment is set to true and cache-environment-key is not specified, setup-micromamba will use the default cache key (micromamba-environment). Similar behavior applies to cache-downloads and cache-downloads-key.

[!NOTE] Note that the specified cache key is only the prefix of the real cache key. setup-micromamba will append a hash of the environment file and the custom-args as well as the environment name and OS to the cache key.

- uses: mamba-org/setup-micromamba@v1
  with:
    environment-file: environment.yml
    # only cache environment
    cache-environment: true
    cache-downloads: false

- uses: mamba-org/setup-micromamba@v1
  with:
    environment-file: environment.yml
    # persist only for runs on this commit.
    cache-environment-key: environment-${{ github.sha }}
    cache-downloads-key: downloads-${{ github.sha }}

- name: Get current date
  id: date
  run: echo "date=$(date +%Y-%m-%d)" >> "${GITHUB_OUTPUT}"
- uses: mamba-org/setup-micromamba@v1
  with:
    environment-file: environment.yml
    # persist on the same day.
    cache-environment-key: environment-${{ steps.date.outputs.date }}
    cache-downloads-key: downloads-${{ steps.date.outputs.date }}

See Notes on caching for more information about caching.

Debugging

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

Debug logging of the action

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

- uses: mamba-org/setup-micromamba@v1
  env:
    ACTIONS_STEP_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, see the official documentation.

Debug logging of micromamba

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

- uses: mamba-org/setup-micromamba@v1
  with:
    environment-file: environment.yml
    # supports off, critical, error, warning, info, debug, trace
    log-level: debug

If nothing is specified, setup-micromamba will default to warning or debug depending on if debug logging is enabled for the action.

Self-hosted runners

On self-hosted runners, it may happen that some files are persisted between jobs. This can lead to problems when the next job is run.

Post-action cleanup

To avoid persistence between jobs, you can use the post-cleanup input to specify the post cleanup behavior of the action (i.e., what happens after all your commands have been executed).

There is a total of 4 options:

• none: No cleanup is performed.
• shell-init: The shell initialization files are removed by executing micromamba shell deinit -s <shell>.
• environment: Shell initialization files and the installed environment are removed.
• all: Shell initialization files as well as the micromamba root folder and the binary are removed.

If nothing is specified, setup-micromamba will default to shell-init.

- uses: mamba-org/setup-micromamba@v1
  with:
    environment-file: environment.yml
    post-cleanup: environment

Specify the path of the micromamba binary

You also might want to alter the default micromamba installation location to a temporary location. You can use micromamba-binary-path: ${{ runner.temp }}/bin/micromamba to do this.

- uses: mamba-org/setup-micromamba@v1
  with:
    environment-file: environment.yml
    # ${{ runner.temp }}\Scripts\micromamba.exe on Windows
    micromamba-binary-path: ${{ runner.temp }}/bin/micromamba

You can also use a pre-installed micromamba binary by setting micromamba-binary-path to the path of the binary and specifying download-micromamba: false.

- uses: mamba-org/setup-micromamba@v1
  with:
    environment-file: environment.yml
    download-micromamba: false
    # you don't need to specify this if micromamba is already on PATH
    micromamba-binary-path: /usr/local/bin/micromamba
    generate-run-shell: false # this would generate a file next to the micromamba binary

More examples

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

Notes on caching

Branches have separate caches

Due to a security limitation of GitHub Actions any caches created on a branch will not be available on the main/parent branch after merging. This also applies to PRs.

In contrast, branches can use a cache created on the main/parent branch.

See also this thread.

When to use download caching

Please see this comment for now.

When to use environment caching

Please see this comment for now.

About login shells...

Some shells require special syntax (e.g. bash -leo pipefail {0}). You can set this up with the defaults option:

jobs:
  myjob:
    defaults:
      run:
        shell: bash -leo pipefail {0} {0}

# or top-level:
defaults:
  run:
    shell: bash -leo pipefail {0} {0}
jobs:
  ...

Find the reasons below (taken from setup-miniconda):

• Bash shells do not use ~/.profile or ~/.bashrc so these shells need to be explicitly declared as shell: bash -leo pipefail {0} on steps that need to be properly activated (or use a default shell). This is because bash shells are executed with bash --noprofile --norc -eo pipefail {0} thus ignoring updated on bash profile files made by micromamba shell init bash.
• Cmd shells do not run Autorun commands so these shells need to be explicitly declared as shell: cmd /C call {0} on steps that need to be properly activated (or use a default shell). This is because cmd shells are executed with %ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}"" and the /D flag disabled execution of Command Processor/Autorun Windows registry keys, which is what micromamba shell init cmd.exe sets.

For further information, see jobs.<job_id>.steps[*].shell and this thread.

Use in NPM scripts

When used in NPM scripts, setup-micromamba provides a convenient way to download micromamba and create conda environments.

Set options through environment variables in invocation. If micromamba has already been downloaded or an environment already exists, it will not be recreated.

Example:

  "scripts": {
  [...]
    "micromamba": "MICROMAMBA_ROOT_PATH=micromamba CREATE_ENVIRONMENT=true CREATE_ARGS=\"python=3.11\" ENVIRONMENT_NAME=test-env setup-micromamba",
  [...]

Development

1. Clone this repository.
2. Run pnpm install inside the repository (if you don't have pnpm installed, you can install it with npm install -g pnpm or brew install pnpm).
3. Run pnpm run dev for live transpilation of the TypeScript source code.
4. To test the action, you can run act (inside docker) or test.sh (on your local machine).