Release and publish a new Ruby SDK version automatically: a step-by-step guide

Introduction

Maintaining a well-organized changelog, releasing a new version of an SDK, then publishing it into a package repository. All these are tedious, repetitive chores that can be automated to save valuable developer time.

In this tutorial, you will learn how to set up tools that do just that. You will walk through the following steps:

1. Set up a Github Action to release a new SDK version
2. Publish a new SDK version:
   1. Create a Rubygems account, 
   2. Create a Rubygems API key and store it in GitHub securely
   3. Set up a GitHub workflow to auto-publish a new SDK version

Prerequisities

This tutorial assumes that you have already developed a functional SDK and pushed it into a GitHub repository.

Release a new version

Owner + Developer: Set up a Github Action to release new SDK versions

To avoid the tedious task of updating the changelog and releasing new versions manually, we recommend using the Github Action release-please. This Action keeps track of code changes since the last release and maintains a pull request with changelog and version changes based on your commit messages. When the time is right to release a new SDK version, all you need to do is merge the pull request.

Follow these steps to set up the Action:

Owner:

1. In your Github repository, go to Settings > Actions > General and make sure that the option “Allow Github Actions to create and approve pull requests” is checked.

Developer:

2. In the root folder of your project, create a directory .github/workflows/. This is where GitHub Action configuration files should always be stored.
3. In this directory, create a new configuration YAML file. Name it release-please.yml.
4. Copy the following code into your configuration file:

# This workflow opens and updates a pull request with a new package version
# based on code changes.


# The pull request updates the version in version.rb, updates the changelog
# and creates release tags.


# For more information, see https://github.com/marketplace/actions/release-please-action


on:
 push:
   branches:
     - master
  
permissions:
 contents: write
 pull-requests: write


name: release-please


jobs:
 release-please:
   runs-on: ubuntu-22.04
   steps:
     - uses: google-github-actions/release-please-action@v3.7.10
       with:
         release-type: ruby
         package-name: release-please-action
         version-file: "lib/your_gem_name/version.rb"
         pull-request-title-pattern: "chore(release): ${version}"
         pull-request-header: ":robot: Merge this PR to release a new version"

Make sure you change the line `version-file: "lib/your_gem_name/version.rb"` to reflect the location of your `version.rb` file. Note that if the main branch of your project has a different name than `master` (for example `main`), you need to change this on Line 13.

5. If your SDK has been released before, make sure that the commit with the latest release has a version tag attached to it (in the format “v2.1.1”) and that this tag has been pushed to GitHub. The release-please tool determines the next version number based on this tag. Unless such a tag exists, release-please will suggest “v1.0.0” as the next version number.
6. Commit all these changes and push them into the Github repository. Now the workflow is set up. The next time someone adds something releasable with a conventional commit message (i.e. with a prefix fix: or feat:), release-please will open a pull request . As you add new code, the pull request will be updated automatically. When you are eventually ready to roll out a new version of your SDK, simply merge this pull request. The version will be released and the updated SDK will be published to Rubygems.

Note that release-please follows the Semantic Versioning (SemVer) specification, which means that it will automatically generate version numbers based on the significance of your changes. For example, if you have made breaking changes, it will generate a major version number; if you have added new features, it will generate a minor version number; and if you have fixed bugs, it will generate a patch version number. By following this convention, you can make it easy for your users to understand the impact of each new version of your SDK.

Your commit messages should follow the Conventional Commits format for release-please to be able to determine the significance of your changes and generate the correct version number. This means that you should follow a specific format for your commit messages, such as "feat: add new feature" for a new feature, "fix: resolve bug" for a bug fix, and "chore: update dependencies" for a non-code change. By using this format consistently, you can ensure that release-please generates version numbers and changelogs correctly based on the significance of your changes. You can, however, always update the changelog manually in the open pull request before the release.

Publish a new version

Owner: Create a Rubygems account, get an API key and store it in GitHub securely

1. Before publishing your SDK for the first time, you need to create a Rubygems account here.
2. Go to Settings > API keys and input your password when prompted. Then click on the “New API key” button. Choose a name for your API key, make sure the “Push rubygem” scope is selected and create the API key.
3. Copy the API key.
4. Go to the GitHub page of your project. Go to Settings > Security > Secrets and Variables > Actions and click on the “New repository secret” button.
5. Enter `RUBYGEMS_API_KEY` in the Name field.
6. Enter the API key you copied in Step 3 in the Secret field. Click on the “Add secret” button to confirm.

Developer: Automate SDK publishing using GitHub workflows

You can set up a GitHub workflow that will automatically publish your SDK to the Rubygems repository after you push a release commit into the GitHub origin repository:

1. In your project, go to the folder .github/workflows (or create it if it does not exist yet) and  create a new configuration YAML file. Name it for example rubygems-publish.yml .
2. Copy the following code into your configuration file:

# This workflow will publish a gem to rubygems.org when a release is created


name: Publish Gem


on:
  push:
    branches:
      - master


jobs:
  publish:
    if: contains(github.event.head_commit.message, 'chore(release)')
    runs-on: ubuntu-22.04


    steps:
      - uses: actions/checkout@v3.5.3
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: "2.7"
      - run: gem build
      # add RubyGems API key into the credentials file and update permissions
      - run: |
          cat << EOF > ~/.gem/credentials
          ---
          :rubygems_api_key: ${RUBYGEMS_API_KEY}
          EOF
          chmod 0600 ~/.gem/credentials
        env:
          RUBYGEMS_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
      - run: gem push *.gem

Note that if the main branch of your project has a different name than `master` (for example `main`), you need to change the name on Line 8.

3. Commit this new file to your project main branch and push these changes into the GitHub origin repository.

Now the GitHub Action is ready. Note that for the Action to work, you need to add the `RUBYGEMS_API_KEY` to GitHub secrets first.

The Action is triggered when you push a commit into your main project branch with the commit message containing the phrase `chore(release)`. If you took the steps described in the “Release a new version” section of this manual, the publish Action will be triggered when you merge the pull request opened by the release-please Action.

Conclusion

This guide walked you through the process of setting up automatic tools for releasing a new version of a Ruby SDK and publishing it into the Rubygems repository. By automating these processes, you save time and resources that you can instead dedicate to developing your code.

If you need help with SDK development or automation setup, our team of experts is ready to assist you. We can help you streamline your SDK development process, optimize your automation setup, and save you time and money in the process.

So why not get in touch with us today and see how we can help you take your SDK development to the next level?

Need an automated release for another technology?

• Automated release for JavaScript
• Automated release for PHP
• Explore our tool that automates all technologies at once

You might also be interested in:
SDK: What is it and how can it help my business? 

Author

Prokop Simek

CEO

With over 12 years of experience in software engineering, I leverage my expertise to bridge the gap between business goals and technology for our clients.