gem_package

gem_package installs Ruby gems on a node with the gem program of the Ruby on the node. Use it for a gem that the node needs by itself, such as Bundler. An application's own gems, which its Gemfile.lock lists, are bundler_project_dependencies.

What gem_package shares with the other language and tool installers, such as run_as_user_account, gem_program_path, env, and how a change becomes a tracked input, is in what the installers share and in the design's what these modules share. run_as_user_account is required, including when the installer runs as root.

Set up

Ruby and gem come from the distribution's packages:

- when: {equals: ["{{ .node.package_manager }}", apt]}
  apt_package: {packages: [{name: ruby, version: newest_when_first_installed}]}
- when: {equals: ["{{ .node.package_manager }}", dnf]}
  dnf_package: {packages: [{name: ruby, version: newest_when_first_installed}, {name: rubygems, version: newest_when_first_installed}]}

Inputs

  • packages (list of mappings; required): each entry requires name and version; version is an exact version; newest_when_first_installed: installs the newest version when the package is missing, then never upgrades it; newest_on_every_run: also upgrades it to the newest version on every run; with state: absent, name only; gem_package also accepts an exact version
  • state (present or absent; default present): present follows each entry's version choice; absent removes every version, or with an exact version only that one
  • gem_program_path (string; default found on the standard path): a written value must be absolute; the gem program to run when it is not gem on the standard path, such as one that rbenv provides
  • run_as_user_account (string; required): local account that runs gem, as shell's run_as_user_account; RubyGems installs into the account's own directory when it cannot write the system's
  • env (mapping; optional): environment variables for gem, such as GEM_HOME; values may be secrets

Outputs

The node task's result holds these fields. A later node task reads them as .node_tasks.<id>.<field>, where <id> is the node task's id.

  • status
  • change
  • value

What a dryrun reports

Lists the gems it would install or remove; for newest_on_every_run it asks gem outdated.

Retries and time limits

Bounded automatic retries by default; retry: false turns them off.

The node task takes the time limits time_limit and time_limit_per_try; without them, the project's node_task_defaults apply. mmx describe-module task describes the settings every node task accepts.

Examples

Install one version of a gem

- gem_package:
    packages:
      - name: bundler
        version: "2.5.23"
    run_as_user_account: root

Each packages entry states an exact version or a version keyword. RubyGems, the package manager that provides gem on the node, keeps several versions of a gem side by side. The example's gem_package node task ensures Bundler 2.5.23 is installed without removing other installed Bundler versions.

Keep gems at the newest version, or remove them

- gem_package:
    packages:
      - name: rake
        version: newest_on_every_run
    run_as_user_account: root

- gem_package:
    packages:
      - name: bundler
        version: "2.5.23"
    state: absent
    run_as_user_account: root

What the version keywords do is in Package versions. state: absent removes every installed version of each named gem, or only the exact version written in the gem's packages entry.

How it works

MMX asks gem list what is installed and runs gem install or gem uninstall only for what differs. A dryrun lists the gems MMX would install or remove; for newest_on_every_run MMX asks gem outdated. MMX passes every gem needing installation or an upgrade to a single gem install command, attaching each exact version to the corresponding gem name.

Tracked input: the installed versions of the named gems.

Tested on

Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10.

The suite language_installers.py runs on Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, and AlmaLinux 10, with Ruby from the distribution's packages, and covers gem_package with an exact version.

Why it works this way

  • The task states each package's version choice. Presence alone does not say whether future runs should upgrade. See the shared design's required-settings rule.
  • The task names the installer's account. Package installers can run package code, so running as root must be an explicit choice.

This page is docs/reference/modules/gem_package.md in the MMX repository.