> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# circleci/ruby

Easily cache and install your Ruby Gems automatically, run parallel Rspec tests, or just install Ruby.


## Commands

### install

Install Ruby within a build. To be used in a Linux distro with Apt available.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `openssl-path` | string |  | Directory where OpenSSL is intalled. This will overwrite the value of --with-openssl-dir in the rvm install commmand. Set this if you need to use an OpenSSL version different to 1.0.1 (rvm default). The version must be already installed.
 |
| `version` | string |  | Ruby version. This can be a literal value (e.g, `2.7.5`). You can also pass in a string to be evaluated. For example, `${MY_RUBY_VERSION}` or `$(cat foo/bar/.ruby-version)`.
 |

### install-deps

Install gems with Bundler.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `app-dir` | string | . | Path to the directory containing your Gemfile file. Not needed if Gemfile lives in the root.
 |
| `bundler-version` | string |  | Configure which version of bundler to install and utilize. By default, it gets the bundler version from Gemfile.lock, but if it is not working use this to override.
 |
| `clean-bundle` | boolean | false | Run `bundle clean --force` after `bundle install` to clean Bundler before saving dependencies to cache. By default, it is set to false.
 |
| `gemfile` | string | Gemfile | Name of your Gemfile file. |
| `include-arch-in-cache-key` | boolean | true | If true, this cache bucket will only apply to jobs running on the same architecture.
 |
| `include-branch-in-cache-key` | boolean | true | If true, this cache bucket will only apply to jobs within the same branch.
 |
| `key` | string | gems-v1 | The cache key to use. The key is immutable. |
| `no_output_timeout` | string | 10m | Specify a timeout for the bundle install command. By default, it is set to 10 minutes.
 |
| `only-use-gemfile-checksum-cache-key` | boolean | false | When enabled only uses the cache key that contains the Gemile.lock checksum for restoring cache. |
| `override-cache-file` | string |  | Specify an alternative file to use in the cache key
 |
| `path` | string | ./vendor/bundle | Installation path. By default, it will run bundle with `--deployment` flag and installs gems to the vendor/bundle directory.
 |
| `pre-install-steps` | steps |  | Steps that will be executed between installing bundler, and running bundle install
 |
| `with-cache` | boolean | true | Enable automatic caching of your gemfile dependencies for increased speed. |

### rspec-test

Test with RSpec. You have to add `gem 'rspec_junit_formatter'` to your Gemfile. Enable parallelism on CircleCI for faster testing.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `app-dir` | string | . | Path to the directory containing your Gemfile file. Not needed if Gemfile lives in the root.
 |
| `include` | string | spec/**/*_spec.rb | Glob to define where your test files are kept within your repository. Should multiple globs be required, they must be passed in a comma separated string (e.g.: "{spec/**/*_spec.rb,spec2/**/*_spec.rb}").
 |
| `label` | string | RSpec Tests | Task label |
| `no_output_timeout` | string | 10m | Allows you to specify the no_output_timeout for the rspec test. Defaults to 10m.
 |
| `order` | string |  | Use the order parameter to tell RSpec how to order the files, groups, and examples. Available options can be found at: https://rspec.info/features/3-12/rspec-core/command-line/order
 |
| `out-path` | string | /tmp/test-results/rspec | Where to save the rspec.xml file. Will automatically be saved to test_results and artifacts on CircleCI. |
| `rerun-fail` | boolean | true | Enabling the option uses circleci tests run command and allows the "Rerun failed tests only" feature. This feature helps optimize test execution by re-running only the failed tests from previous test run data. More information can be found at: https://circleci.com/docs/rerun-failed-tests-only
 |
| `tag` | string |  | Use the tag parameter to tell RSpec to run only examples with (or without) a specified tag(s). Multiple tags should be separated by a space. Available options can be found at: https://rspec.info/features/3-12/rspec-core/command-line/tag
 |

### rubocop-check

Check the code by Rubocop. You have to add `gem 'rubocop'` to your Gemfile. Enable parallelism on CircleCI for faster checking.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `app-dir` | string | . | Path to the directory containing your Gemfile file. Not needed if Gemfile lives in the root.
 |
| `check-path` | string | . |  |
| `format` | string | progress | Customize the formatter for rubocop https://docs.rubocop.org/rubocop/0.88/formatters.html |
| `label` | string | Rubocop Checks | Task label |
| `out-file-name` | string | check-results.xml | Customize the name of the output file |
| `out-path` | string | /tmp/rubocop-results | Customize the directory of output file |
| `parallel` | boolean | true | Use available CPUs to execute inspection in parallel.
 |

## Executors

### default

Select the version of Ruby to use. Uses CircleCI's highly cached convenience images built for CI.
Any available tag from this list can be used: https://hub.docker.com/r/cimg/ruby/tags


| Parameter | Type | Default | Description |
|---|---|---|---|
| `resource_class` | string | medium | The resources_class of the instance to run on. Defaults to Medium. |
| `tag` | string | 2.7 | The `cimg/ruby` Docker image version tag. |

## Examples

### install_ruby

For environments where Ruby is not pre-installed. (Recommended: It is faster and more deterministic to use a Docker image with Ruby pre-installed. Installing Ruby at run-time is not advised unless required.)


```yaml
version: '2.1'
orbs:
  ruby: circleci/ruby@x.y
jobs:
  build:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - ruby/install:
          version: '2.7'
      - run: echo "Ruby 2.7 has been installed"
workflows: null
```

### ruby_rails_sample_app

Build and test a full Ruby Rails application with a Postgres database using RSpec.
View the full sample application source: https://github.com/CircleCI-Public/circleci-demo-ruby-rails/


```yaml
version: '2.1'
orbs:
  node: circleci/node@x.y
  ruby: circleci/ruby@x.y
jobs:
  build:
    docker:
      - image: cimg/ruby:2.7-node
    steps:
      - checkout
      - ruby/install-deps
      - node/install-packages:
          cache-key: yarn.lock
          pkg-manager: yarn
  checking:
    docker:
      - image: cimg/ruby:2.7-node
    steps:
      - checkout
      - ruby/install-deps
      - ruby/rubocop-check:
          format: progress
          label: Inspecting with Rubocop
  test:
    docker:
      - image: cimg/ruby:2.7-node
      - environment:
          POSTGRES_DB: rails_blog_test
          POSTGRES_PASSWORD: ''
          POSTGRES_USER: circleci-demo-ruby
        image: circleci/postgres:9.5-alpine
    environment:
      BUNDLE_JOBS: '3'
      BUNDLE_RETRY: '3'
      PGHOST: 127.0.0.1
      PGPASSWORD: ''
      PGUSER: circleci-demo-ruby
      RAILS_ENV: test
    parallelism: 3
    steps:
      - checkout
      - ruby/install-deps
      - node/install-packages:
          cache-key: yarn.lock
          pkg-manager: yarn
      - run:
          command: dockerize -wait tcp://localhost:5432 -timeout 1m
          name: Wait for DB
      - run:
          command: bundle exec rails db:schema:load --trace
          name: Database setup
      - ruby/rspec-test:
          include: spec/**/*_spec.rb
workflows:
  build_and_test:
    jobs:
      - build
      - checking
      - test:
          requires:
            - build
```