Awesome
setup-micromamba
GitHub Action to set up the micromamba package manager.
Usage
- uses: mamba-org/setup-micromamba@v1
with:
micromamba-version: '1.5.6-0' # any version from https://github.com/mamba-org/micromamba-releases
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 bycreate-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 themicromamba create
command to create the environment from the environment file and there, extra specs are specified by adding them as extra arguments to themicromamba 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 therun:
section of your workflow. See the official documentation and ADR 0277 for more information about how theshell:
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 thecustom-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 executingmicromamba 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 control the download behavior of micromamba with the options download-micromamba
and micromamba-binary-path
.
Micromamba on $PATH | download-micromamba | micromamba-binary-path | Behavior |
---|---|---|---|
No | unset | unset | Download to default location |
No | unset | set | Download to specified path |
No | false | unset | Error |
No | false | set | Use binary (absolute path) |
No | true | unset | Download to default location |
No | true | set | Download to specified path |
Yes | unset | unset | Use binary (from PATH) |
Yes | unset | set | Download to specified path |
Yes | false | unset | Use binary (from PATH) |
Yes | false | set | Use binary (specified path) |
Yes | true | unset | Download to default location |
Yes | true | set | Download to specified path |
- 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}
# or top-level:
defaults:
run:
shell: bash -leo pipefail {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 asshell: bash -leo pipefail {0}
on steps that need to be properly activated (or use a default shell). This is because bash shells are executed withbash --noprofile --norc -eo pipefail {0}
thus ignoring updated on bash profile files made bymicromamba shell init bash
. - Cmd shells do not run
Autorun
commands so these shells need to be explicitly declared asshell: 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 ofCommand Processor/Autorun
Windows registry keys, which is whatmicromamba shell init cmd.exe
sets.
For further information, see
jobs.<job_id>.steps[*].shell
and this thread.
Development
- Clone this repository.
- Run
pnpm install
inside the repository (if you don't havepnpm
installed, you can install it withnpm install -g pnpm
orbrew install pnpm
). - Run
pnpm run dev
for live transpilation of the TypeScript source code. - To test the action, you can run
act
(inside docker) ortest.sh
(on your local machine).