Skip to main content
Last updated: 19 Mar 2024

Publish a Ruby gem


For conventions around naming, refer to the RubyGems naming guide and the GOV.UK naming policy.

Follow Semantic Versioning and put version updates in their own commit.

Follow the file and directory conventions used by Bundler.

Releasing gem versions

Use GitHub Actions for releasing gems, with our shared publish workflow and the ALPHAGOV_RUBYGEMS_API_KEY secret. For builds with extra needs (e.g. the npm build step in govuk_publishing_components), copy and adapt the shared workflow.

Contact a GOV.UK GitHub Owner to grant your repository access to the secret.

Automatically releasing patch-level versions

Use the shared autorelease workflow and the GOVUK_CI_GITHUB_API_TOKEN secret to automatically raise a PR to perform a patch-level version bump if the gem has unreleased changes, and all of those changes were authored by Dependabot.

After a developer approves and merges that PR, the publish-rubygem workflow (if present) will automatically publish the next release to Rubygems.

Ruby version compatibility

Ensure gems are compatible with all supported minor Ruby versions, specifying the minimum minor Ruby version in the gemspec file. For example: spec.required_ruby_version = ">= 3.1".

Do not specify a patch (or “tiny”) Ruby version unless there is a particular issue with a Ruby patch release.

The .ruby-version file should be the same minor version level as the required_ruby_version in the gemspec, it is typically the most recent patch version. For example: spec.required_ruby_version >= "3.1" would correlate to a .ruby-version of 3.1.4.

When Ruby versions reach end-of-life (typically April) we update gems to drop support for that Ruby version and update the .ruby-version files to the next supported version. For example, when Ruby 2.7 reached end of life, we dropped 2.7 from the test matrices and we updated the .ruby-version file to be the most recent release of the 3.0 branch, which in March 2023 was 3.0.5 (see example).

We should then release the updated gem as a minor version. In the past, our policy was to release as a major version, but this was superfluous given that the change is low risk (Dependabot shouldn’t even raise a PR unless the upstream app is on a supported Ruby version). It also limited our ability to benefit from the automated workflows agreed in RFC-156, which apply only to patch and minor version upgrades. Note that patch versions are generally reserved only for bug fixes.