README.md

October 23, 2025 ยท View on GitHub

appraisal-run

Builds individual Docker containers from each of your gemfiles and runs the given command.

Intro

appraisal-run is a super simple CLI tool for running commands inside Docker containers. It's designed to operate across multiple gemfiles, such as the ones produced by the Appraisal tool.

Appraisal doesn't really have a way to run commands across all your gemfiles. It can install gems from each gemfile, but often you need to specify a version of Ruby as well. Appraisal does not come with a mechanism for running installs across multiple versions of Ruby. That's where appraisal-run comes in.

Usage

The following examples use the following Appraisal file:

appraise 'rails-7.2' do
  ruby '~> 3.3'
  gem 'rails', '~> 7.2.0'
end

appraise 'rails-8.0' do
  ruby '~> 3.4'
  gem 'rails', '~> 8.0.0'
end

Use the ruby gemfile method to lock each generated gemfile to a particular version of Ruby. If no ruby version is specified, appraisal-run will use the version of the currently running ruby executable.

After running appraisal generate, there should be two gemfiles in the gemfiles/ directory.

Make sure you have Docker (or Podman) installed. If you're using Podman, make sure you have the Docker compatibility settings turned on so the docker executable is available.

Finally, install appraisal-run by adding it to your gemfile or installing it via gem install, and run it like so:

appraisal-run gemfiles/*.gemfile -- bundle exec rake

The appraisal-run executable accepts a list of gemfile paths as arguments. The command to run in each container is specified after an -- argument separator.

appraisal-run will iterate over each gemfile and:

  1. pull the Docker image for the appropriate version of Ruby.
  2. run bundle install inside a new container. Gems from the bundle are installed into vendor/bundle so they can be re-used across invocations.
  3. run the specified command.

appraisal-run mounts the current working directory inside the container so it has access to your project's code, tests, etc.

Cusomizing the Docker Image

By default, appraisal-run pulls and runs the official Docker image for the version of Ruby specified in the gemfile (eg. ruby:3.4, ruby:2.7, etc). However, custom Docker images are also supported. If appraisal-run detects a Dockerfile with the same name as the gemfile, it will be used to build an image, and that image will be used to execute the given command.

For example, given a gemfile at gemfiles/foo.gemfile, appraisal-run will look for a Dockerfile at gemfiles/foo.dockerfile.

License

Licensed under the MIT license. See LICENSE for details.

Authors