Migrate Travis CI to GitHub Actions for Ruby

This article goes over how to migrate from Travis CI to GitHub Actions for a Ruby project on GitHub.

Travis CI

Given the .travis.yml:

# .travis.yml
language: ruby
cache: bundler
env:
  global:
    - NOKOGIRI_USE_SYSTEM_LIBRARIES=true # speeds up the installation of `html-proofer`
script:
  - bundle exec jekyll build --safe
  - bundle exec htmlproofer _site

GitHub Actions

First make the directory .github/workflows/:

mkdir -p .github/workflows/

Create .github/workflows/build.yml:

touch .github/workflows/build.yml

Add the workflow that runs a single job:

# .github/workflows/build.yml
name: build
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    env:
      NOKOGIRI_USE_SYSTEM_LIBRARIES: true # speeds up the installation of `html-proofer`
    steps:
      - uses: actions/checkout@v2
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: 2.6 # not needed if `.ruby-version` exists
          bundler-cache: true # runs `bundle install` and caches installed gems automatically
      - run: bundle exec jekyll build --safe
      - run: bundle exec htmlproofer _site

To test multiple versions of Ruby, update the workflow:

# .github/workflows/build.yml
name: build
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    env:
      NOKOGIRI_USE_SYSTEM_LIBRARIES: true # speeds up the installation of `html-proofer`
    strategy:
      matrix:
        ruby-version: [2.6, 3.0]
    steps:
      - uses: actions/checkout@v2
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: ${{ matrix.ruby-version }}
          bundler-cache: true # runs `bundle install` and caches installed gems automatically
      - run: bundle exec jekyll build --safe
      - run: bundle exec htmlproofer _site

The Ruby workflow is inspired by the template.

Workflow

Here’s a breakdown of what each YAML field does.

name

name is the workflow name. It’s optional and you can name it whatever you like:

name: CI build

on

on is the event that triggers the workflow. In our example, git push triggers our workflow.

To add the pull_request event:

on: [push, pull_request]

Which is the same thing as:

on:
  push:
    branches: [$default-branch]
  pull_request:
    branches: [$default-branch]

jobs

jobs are the jobs that the workflow runs. In our example, we have a single job named build:

jobs:
  build:
    # ...

runs-on

runs-on is the environment that the workflow runs on. To specify an OS version:

runs-on: ubuntu-18.04

strategy.matrix

strategy.matrix is the build matrix. In our example, we’re running a job for a single ruby version. To define jobs for multiple ruby versions:

strategy:
  matrix:
    ruby-version: [2.6.0, '3.0', jruby]

steps

steps are the tasks of a job. In our example, we’re using the GitHub Actions:

actions/checkout checks out the repository and ruby/setup-ruby sets up the Ruby environment:

steps:
  - uses: actions/checkout@v2
  - uses: ruby/setup-ruby@v1
    with:
      ruby-version: 2.6 # not needed if `.ruby-version` exists
      bundler-cache: true # runs `bundle install` and caches installed gems automatically

steps.run

steps.run runs the commands. Since setup-ruby installs bundler, it can be used to execute commands:

steps:
  - run: bundle install

env

env sets the environment variables for the entire workflow or an individual step. See env and jobs.<job_id>.steps.env.

Although Travis CI sets default environment variables, we don’t have to set CI=true for our job since actions/checkout@v2 does it for us:

jobs:
  build:
    env:
      CI: true