How to create GitHub actions in Ruby

GitHub Actions enables you to create custom workflows for your software development life cycle and automate them within your GitHub repository. In this article, we'll walk through how to create a GitHub action in Ruby to automate your continuous integration pipeline.

Note: Before you start, you'll need a basic understanding of GitHub Actions. If you're not familiar with GitHub Actions, first read the GitHub guide to understanding GitHub Actions, which explains essential concepts and terminology.

Why GitHub Actions?

GitHub Actions is becoming increasingly popular with organisations who are looking to automate the workflows in their CI/CD pipeline. GitHub Actions is free to use in public and private repositories, with limited free minutes and storage per month. It's also very easy to configure GitHub Actions, as the workflow is available in the repository, with no need for any additional configuration. There is a substantial library of built-in actions available for free, which makes it easy to get started. You can also compose your workflow by using multiple actions.

Creating a GitHub action in Ruby

Much has been documented about how to create a GitHub action in JavaScript. The GitHub guide to creating a JavaScript action walks through the steps. However, in Ruby, it's not as straightforward.

You have two options:

1. Using a Dockerfile.
2. Using the setup-ruby GitHub action. (Recommended).

Using a Dockerfile

To create a GitHub action in Ruby using a Dockerfile, you'll need to:

1. Create a minimal Ruby project that contains a Ruby file, for example run.rb, in the root directory and a Gemfile to manage dependencies in your project.

2. Create a Dockerfile in the root of your project. Add run.rb as the entry point.

   FROM ruby:2.7.0
   
   RUN gem install bundler
   
   RUN mkdir -p /runner/action
   
   WORKDIR /runner/action
   
   COPY Gemfile* ./
   
   COPY run.rb ./
   
   RUN bundle install --retry 3
   
   ENV BUNDLE_GEMFILE /runner/action/Gemfile
   
   RUN chmod +x /runner/action/run.rb
   
   ENTRYPOINT ["ruby", "/runner/action/run.rb"]
   

3. Create an action.yml metadata file that defines the input/output and the information required to publish your action. You can customise your action by using the metadata syntax for GitHub Actions, including customising how your action will look. Here is an example:

   name: 'Unique name of your action'
   author: '[email protected]'
   description: 'description of what action does'
   branding:
     icon: code
     color: red
   runs:
     using: 'docker'
     image: 'Dockerfile'
   

4. Push your changes to your default branch (master/main).

5. Publish the GitHub action.

Here is an example of a Simply Business public GitHub action - the deploy status action. The deploy status action uses the Octokit library to call the GitHub API and create statuses that can be used to block and unblock deploys in the pipeline.

Using the action in your project

To use the action you created in your project:

1. Create a workflow file .github/workflows/my-workflow.yml in your repository, which will be triggered by an event such as when a pull request is opened or changes are pushed to the repository.

   name: 'my workflow'
   on:
     pull_request:
       types: [opened, synchronize]
   permissions:
     contents: read
     statuses: write # change according to the permissions your workflow needs. For more info, visit: https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#permissions
   jobs:
     build:
       runs-on: ubuntu-20.04
       steps:
         - uses: org-name/[email protected]
           env:
             ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }} # provided by GitHub. You can use this to access the GitHub API.
   

2. Open a PR and check that it runs your Ruby action in the actions tab of your repository. If not, check the workflow to ensure there are no typos or syntax errors.

Using the setup-ruby action (Recommended)

Docker container actions are great, but they don't take advantage of the caching action that GitHub provides. Therefore, each run can take a long time. We can save a lot of time (over half) by caching bundler dependencies after the first run. It not only saves time but reduces the number of minutes taken to run the action, thereby saving money if you're using a private repository.

Here are the steps for creating an action using the setup-ruby action:

1. Create a minimal Ruby project with a simple run.rb file, .ruby-version to specify ruby at the root directory and a Gemfile to manage dependencies in your project.
2. Create an action.yml metadata file. Note here we are not using a Dockerfile in the run section, instead using a composite action to run the Ruby code. You can customise your action by using the metadata syntax for GitHub Actions, including customising how your action will look.

Here is an example:

name: 'Unique name of your action'
description: 'Description of what your action does'
author: '[email protected]'
branding:
  icon: filter
  color: red
runs:
  using: 'composite'
  steps:
    - run: |
        bundle exec ruby run.rb
      shell: bash

1. Push the changes to your default branch (master/main).
2. Publish the GitHub action.

Here is an example of a Simply Business public GitHub action - dobby. Dobby uses the Octokit library to call the GitHub API to update the gem version based on a comment added to a pull request.

Using the action in your workflow

To use the action in your project, you'll need to add some additional steps in your workflow:

1. Check out the repository that will use the action, and then use the setup-ruby action. Create a workflow file .github/workflows/my-workflow.yml, for example:

   name: 'my workflow'
   on:
     pull_request:
       types: [opened, synchronize]
   permissions:
     contents: read
     statuses: write # change according to the permissions your workflow needs. For more info, visit: https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#permissions
   jobs:
     build:
       runs-on: ubuntu-20.04
       steps:
        - uses: actions/[email protected]
          with:
            repository: 'org-name/[email protected]'
            ref: 'v1.0.0'
        - uses: ruby/setup-ruby@v1
          with:
            bundler-cache: true # runs 'bundle install' and caches installed gems automatically
         - uses: org-name/[email protected]
           env:
             ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }} # provided by GitHub. You can use this to access the GitHub API.
   

2. Open a PR and ensure that it runs in the actions tab of your repository. If not, check the workflow to ensure there are no typos or syntax errors.

Running and debugging GitHub Actions

It's not easy to debug a GitHub action locally, primarily because an action provides a lot of tools and environments (ENV) that are not available locally. That said, there are several things that you can try:

1. act - you can pass an event payload to test locally.
2. action-tmate - debug via ssh shell.
3. Create a test repository and play around by directly changing the workflow in the default branch. I like this option best because you can use the UI editor in GitHub. It also highlights any issue, and you can quickly run the workflow in the same environment with all the environment variables and secrets available.

I hope this article helps you to get started with GitHub actions in Ruby. Enjoy!