Building and testing Ruby

Introduction

This guide shows you how to create a continuous integration (CI) workflow that builds and tests a Ruby application. If your CI tests pass, you may want to deploy your code or publish a gem.

Prerequisites

We recommend that you have a basic understanding of Ruby, YAML, workflow configuration options, and how to create a workflow file. For more information, see:

• Learn GitHub Actions
• Ruby in 20 minutes

Using the Ruby starter workflow

GitHub provides a Ruby starter workflow that will work for most Ruby projects. For more information, see the Ruby starter workflow.

To get started quickly, add the starter workflow to the .github/workflows directory of your repository. The workflow shown below assumes that the default branch for your repository is main.

# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.

# GitHub recommends pinning actions to a commit SHA.
# To get a newer version, you will need to update the SHA.
# You can also reference a tag or branch, but the action may change without warning.

name: Ruby

on:
 push:
 branches: [ main ]
 pull_request:
 branches: [ main ]

jobs:
 test:

 runs-on: ubuntu-latest

 steps:
 - uses: actions/checkout@v2
 - name: Set up Ruby
 uses: ruby/setup-ruby@359bebbc29cbe6c87da6bc9ea3bc930432750108
 with:
 ruby-version: '3.1'
 - name: Install dependencies
 run: bundle install
 - name: Run tests
 run: bundle exec rake

Specifying the Ruby version

The easiest way to specify a Ruby version is by using the ruby/setup-ruby action provided by the Ruby organization on GitHub. The action adds any supported Ruby version to PATH for each job run in a workflow. For more information and available Ruby versions, see ruby/setup-ruby.

Using Ruby's ruby/setup-ruby action is the recommended way of using Ruby with GitHub Actions because it ensures consistent behavior across different runners and different versions of Ruby.

The setup-ruby action takes a Ruby version as an input and configures that version on the runner.

steps:
- uses: actions/checkout@v2
- uses: ruby/setup-ruby@359bebbc29cbe6c87da6bc9ea3bc930432750108
 with:
 ruby-version: '3.1' # Not needed with a .ruby-version file
- run: bundle install
- run: bundle exec rake

Alternatively, you can check a .ruby-version file into the root of your repository and setup-ruby will use the version defined in that file.

Testing with multiple versions of Ruby

You can add a matrix strategy to run your workflow with more than one version of Ruby. For example, you can test your code against the latest patch releases of versions 3.1, 3.0, and 2.7.

strategy:
 matrix:
 ruby-version: ['3.1', '3.0', '2.7']

Each version of Ruby specified in the ruby-version array creates a job that runs the same steps. The ${{ matrix.ruby-version }} context is used to access the current job's version. For more information about matrix strategies and contexts, see "Workflow syntax for GitHub Actions" and "Contexts."

The full updated workflow with a matrix strategy could look like this:

# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.

# GitHub recommends pinning actions to a commit SHA.
# To get a newer version, you will need to update the SHA.
# You can also reference a tag or branch, but the action may change without warning.

name: Ruby CI

on:
 push:
 branches: [ main ]
 pull_request:
 branches: [ main ]

jobs:
 test:

 runs-on: ubuntu-latest

 strategy:
 matrix:
 ruby-version: ['3.1', '3.0', '2.7']

 steps:
 - uses: actions/checkout@v2
 - name: Set up Ruby ${{ matrix.ruby-version }}
 uses: ruby/setup-ruby@359bebbc29cbe6c87da6bc9ea3bc930432750108
 with:
 ruby-version: ${{ matrix.ruby-version }}
 - name: Install dependencies
 run: bundle install
 - name: Run tests
 run: bundle exec rake

Installing dependencies with Bundler

The setup-ruby action will automatically install bundler for you. The version is determined by your gemfile.lock file. If no version is present in your lockfile, then the latest compatible version will be installed.

steps:
- uses: actions/checkout@v2
- uses: ruby/setup-ruby@359bebbc29cbe6c87da6bc9ea3bc930432750108
 with:
 ruby-version: '3.1'
- run: bundle install

Matrix testing your code

The following example matrix tests all stable releases and head versions of MRI, JRuby and TruffleRuby on Ubuntu and macOS.

# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.

# GitHub recommends pinning actions to a commit SHA.
# To get a newer version, you will need to update the SHA.
# You can also reference a tag or branch, but the action may change without warning.

name: Matrix Testing

on:
 push:
 branches: [ main ]
 pull_request:
 branches: [ main ]

jobs:
 test:
 runs-on: ${{ matrix.os }}-latest
 strategy:
 fail-fast: false
 matrix:
 os: [ubuntu, macos]
 ruby: [2.5, 2.6, 2.7, head, debug, jruby, jruby-head, truffleruby, truffleruby-head]
 continue-on-error: ${{ endsWith(matrix.ruby, 'head') || matrix.ruby == 'debug' }}
 steps:
 - uses: actions/checkout@v2
 - uses: ruby/setup-ruby@477b21f02be01bcb8030d50f37cfec92bfa615b6
 with:
 ruby-version: ${{ matrix.ruby }}
 - run: bundle install
 - run: bundle exec rake

Linting your code

The following example installs rubocop and uses it to lint all files. For more information, see RuboCop. You can configure Rubocop to decide on the specific linting rules.

# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.

# GitHub recommends pinning actions to a commit SHA.
# To get a newer version, you will need to update the SHA.
# You can also reference a tag or branch, but the action may change without warning.

name: Linting

on: [push]

jobs:
 test:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v2
 - uses: ruby/setup-ruby@477b21f02be01bcb8030d50f37cfec92bfa615b6
 with:
 ruby-version: 2.6
 - run: bundle install
 - name: Rubocop
 run: rubocop

Publishing Gems

You can configure your workflow to publish your Ruby package to any package registry you'd like when your CI tests pass.

You can store any access tokens or credentials needed to publish your package using repository secrets. The following example creates and publishes a package to GitHub Package Registry and RubyGems.

# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.

# GitHub recommends pinning actions to a commit SHA.
# To get a newer version, you will need to update the SHA.
# You can also reference a tag or branch, but the action may change without warning.

name: Ruby Gem

on:
 # Manually publish
 workflow_dispatch:
 # Alternatively, publish whenever changes are merged to the `main` branch.
 push:
 branches: [ main ]
 pull_request:
 branches: [ main ]

jobs:
 build:
 name: Build + Publish
 runs-on: ubuntu-latest
 permissions:
 packages: write
 contents: read

 steps:
 - uses: actions/checkout@v2
 - name: Set up Ruby 2.6
 uses: ruby/setup-ruby@477b21f02be01bcb8030d50f37cfec92bfa615b6
 with:
 ruby-version: 2.6
 - run: bundle install

 - name: Publish to GPR
 run: |
 mkdir -p $HOME/.gem
 touch $HOME/.gem/credentials
 chmod 0600 $HOME/.gem/credentials
 printf -- "---\n:github: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
 gem build *.gemspec
 gem push --KEY github --host https://rubygems.pkg.github.com/${OWNER} *.gem
 env:
 GEM_HOST_API_KEY: "Bearer ${{secrets.GITHUB_TOKEN}}"
 OWNER: ${{ github.repository_owner }}

 - name: Publish to RubyGems
 run: |
 mkdir -p $HOME/.gem
 touch $HOME/.gem/credentials
 chmod 0600 $HOME/.gem/credentials
 printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
 gem build *.gemspec
 gem push *.gem
 env:
 GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}"