mamba-org/provision-with-micromamba

[DEPRECATED] Use setup-micromamba instead

⛔️ This project is deprecated and no longer gets maintained!

Please use the mamba-org/setup-micromamba action instead.

Migration to setup-micromamba

This action is deprecated and will no longer get maintained due to it being superseded by setup-micromamba. See mamba-org/setup-micromamba#70, mamba-org/provision-with-micromamba#103 and mamba-org/provision-with-micromamba#114 for reasons.

The most important difference for migrating is that in setup-micromamba you need to specify the environment-file argument while provision-with-micromamba assumed environment.yml by default.

extra-specs is now called create-args and should be used for all arguments that micromamba create supports.

Example 1 (environment-file, extra-specs, cache-env, semantic versioning)

- uses: mamba-org/provision-with-micromamba@v16
  with:
    extra-specs: |
      python=3.10
      numpy
    cache-env: true

becomes

  # we now use semantic versioning for the action
  # you could also use `...@v1.4.1`
  # or the git sha directly `...@5d5dbebd87f7b9358c403c7a66651fa92b310105`
- uses: mamba-org/setup-micromamba@v1
  with:
    # environment-file is not assumed anymore
    environment-file: environment.yml
    create-args: >- # beware the >- instead of |, we don't split on newlines but on spaces
      python=3.10
      numpy
    # now called cache-environment
    cache-environment: true

Example 2 (micromamba-version, environment-file: false, channels)

- uses: mamba-org/provision-with-micromamba@main
  with:
    micromamba-version: '1.2.0'
    environment-file: false
    environment-name: myenv
    extra-specs: |
      python=3.10
      numpy
    channels: conda-forge

becomes

- uses: mamba-org/setup-micromamba@v1
  with:
    # all supported versions are fetched from https://github.com/mamba-org/micromamba-releases/releases now and contain the build number
    micromamba-version: '1.2.0-1'
    # don't provide environment-file as argument if you don't want to specify one
    environment-name: myenv
    create-args: >-
      python=3.10
      numpy
    # conda-forge is the default channel now and does not need to be specified

Example 3 (channels, channel-priority)

- uses: mamba-org/provision-with-micromamba@v16
  with:
    environment-file: false
    extra-specs: |
      python=3.10
      numpy
    channels: conda-forge,bioconda
    channel-priority: strict

becomes

- uses: mamba-org/setup-micromamba@v1
  with:
    create-args: >-
      python=3.10
      numpy
    # arguments such as channel or channel-priority that belong in the condarc should be specified there
    # or in a .condarc file which can be referenced with `condarc-file: .condarc`
    condarc: |
      channels:
        - conda-forge
        - bioconda
      channel_priority: strict

---

provision-with-micromamba

GitHub Action to provision a CI instance using micromamba.

Dependencies

provision-with-micromamba requires the curl and tar programs (with bzip2 support). They are preinstalled in the default GitHub Actions environments.

Inputs

environment-file

Required. Path to the environment.yml or .lock file for the Conda environment OR false. If false, only extra-specs will be considered and you should provide channels. If both environment-file and extra-specs are empty, no environment will be created (only micromamba will be installed). See the Conda documentation for more information.

Default value: environment.yml

environment-name

The name of the Conda environment. Defaults to name from the environment.yml file set with environment-file. Required if environment-file is a .lock file or false, unless both environment-file and extra-specs are empty.

micromamba-version

Version of micromamba to use, eg. "0.20". See https://github.com/mamba-org/mamba/releases/ for a list of releases.

Default value: latest

extra-specs

Additional specifications (packages) to install. Pretty useful when using matrix builds to pin versions of a test/run dependency. For multiple packages, use multiline syntax:

extra-specs: |
  python=3.10
  xtensor

Note that selectors (e.g. sel(linux): my-linux-package, sel(osx): my-osx-package, sel(win): my-win-package) are available.

channels

Comma separated list of channels to use in order of priority (eg., conda-forge,my-private-channel)

condarc-file

Path to a .condarc file to use. See the Conda documentation for more information.

channel-priority

Channel priority to use. One of "strict", "flexible", and "disabled". See https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-channels.html#strict-channel-priority for more information.

Default value: strict

cache-downloads

If true, cache downloaded packages across calls to the provision-with-micromamba action. Cache invalidation can be controlled using the cache-downloads-key option.

cache-downloads-key

Custom download cache key used with cache-downloads: true. The default download cache key will invalidate the cache once per day.

cache-env

If true, cache installed environments across calls to the provision-with-micromamba action. Cache invalidation can be controlled using the cache-env-key option.

cache-env-key

Custom environment cache key used with cache-env: true. With the default environment cache key, separate caches will be created for each operating system (eg., Linux) and platform (eg., x64) and day (eg., 2022-01-31), and the cache will be invalidated whenever the contents of environment-file or extra-specs change.

log-level

Micromamba log level to use. One of "trace", "debug", "info", "warning", "error", "critical", "off".

Default value: warning

installer-url

Base URL to fetch Micromamba from. Files will be downloaded from <base url>/<platform>/<version>, eg. https://micro.mamba.pm/api/micromamba/linux-64/latest.

Default value: https://micro.mamba.pm/api/micromamba

condarc-options

More options to append to .condarc. Must be a string of valid YAML:

condarc-options: |
  proxy_servers:
    http: ...

post-deinit

Attempt to undo any modifications done to .bashrc etc. in the post action of the workflow. This is useful for self-hosted runners that keep the state of the system. One of "auto", "true" or "false". If set to "auto", behaves like "true" if the micromamba version used supports micromamba shell deinit (i.e. micromamba>=0.25.0).

Default value: auto

Example usage

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install Conda environment from environment.yml
        uses: mamba-org/provision-with-micromamba@main

      # Linux and macOS
      - name: Run Python
        shell: bash -l {0}
        run: |
          python -c "import numpy"

      # Windows
      # With Powershell:
      - name: Run Python
        shell: powershell
        run: |
          python -c "import numpy"
      # Or with cmd:
      - name: Run cmd.exe
        shell: cmd /C CALL {0}
        run: >-
          micromamba info && micromamba list

Please see the IMPORTANT notes on additional information on environment activation.

Example with customization

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        pytest: ["6.1", "6.2"]
    steps:
      - uses: actions/checkout@v2

      - name: Install Conda environment with Micromamba
        uses: mamba-org/provision-with-micromamba@main
        with:
          environment-file: myenv.yaml
          environment-name: myenvname
          extra-specs: |
            python=3.7
            pytest=${{ matrix.pytest }}

Example with download caching

Use cache-downloads to enable download caching across action runs (.tar.bz2 files).

By default the cache is invalidated once per day. See the cache-downloads-key option for custom cache invalidation.

- name: Install Conda environment with Micromamba
  uses: mamba-org/provision-with-micromamba@main
  with:
    cache-downloads: true

Example with environment caching

Use cache-env to cache the entire Conda environment (envs/myenv directory) across action runs.

By default the cache is invalidated whenever the contents of the environment-file or extra-specs change, plus once per day. See the cache-env-key option for custom cache invalidation.

- name: Install Conda environment with Micromamba
  uses: mamba-org/provision-with-micromamba@main
  with:
    cache-env: true

Notes on caching

Branches have separate caches

Due to a limitation of GitHub Actions any download or environment 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.

More examples

More examples may be found in this repository's tests.

Reference

See action.yml.

IMPORTANT

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

jobs:
  myjob:
    defaults:
      run:
        shell: bash -l {0}

# Or top-level:
defaults:
  run:
    shell: bash -l {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 -l {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 conda init bash. See Github Actions Documentation and thread.
• 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 conda init cmd.exe sets. See Github Actions Documentation.
• sh is not supported. Please use bash.

Development

When developing, you need to

1. install nodejs
2. clone the repo
3. run npm install -y
4. run npm run build after making changes