Add a new Ruby version

Last updated: 23 Nov 2022

The Ruby language is a core part of GOV.UK - most of our applications are written in it.

Managing different versions of Ruby

Each app can use whatever version of Ruby it wants. We manage this with rbenv.

Setting up rbenv

We set up rbenv differently depending on what’s going on:

Interactive login shells: /etc/profile.d/rbenv.sh sets up rbenv
Applications: govuk_setenv and a .ruby-version in the app directory set up rbenv
Deployment: Capistrano uses a non -login shell so we set default_environment (commit)
Testing: Jenkins uses a non-login shell so we add /usr/lib/rbenv/shims to the PATH
Cronjobs: some cronjobs start with /bin/bash -l -c which runs a login shell

Add a new Ruby version in puppet

You will need to build a new fpm package with the new Ruby version. This package can then be copied to Aptly machine, and the new version added to puppet.

Building the fpm package.

Add a new recipe for the ruby version in Packager. The folder name will be the Ruby version, and contain a recipe.rb file. See previous entries for examples. The recipe will require the SHA256 of the version’s tar.gz, available at Ruby cache.
Once the Packager change is merged, build the package.
Then test and upload the package to Aptly. See https://docs.publishing.service.gov.uk/manual/debian-packaging.html#fpm.

Add to Puppet

Once it’s available as a package in Aptly you can install it everywhere using Puppet. However, machines only run apt-get update periodically (nightly) so it might take time for the package to become available.

You can speed things along by SSH'ing into the relevant machine and running sudo apt-get update, then govuk_puppet --test. You should see a successful Ruby install as part of the Puppet run.

You’ll need to do that on jenkins (and, if impatient, each of the ci_agent machines) first to get the PR’s tests passing, and then on the respective machine that your app will run on (e.g. backend).

Update Ruby version in the relevant repos

We use upgrade-ruby-version to automatically raise pull requests in GOV.UK repositories to update Ruby applications. Please note, we manage the Ruby version in gems differently to applications.

It’s advised not to use your personal GitHub account to create the access token required by the script, as another developer will need to approve the PRs. You can use govuk-ci GitHub account. The login credentials for the account can be fetched from govuk-secrets with:

PASSWORD_STORE_DIR=~/govuk/govuk-secrets/pass/2ndline pass github/govuk-ci

Once the PRs are raised, you should test the changes before merge, as follows:

Most apps will run a test suite through CI. You should check the output of this for any Ruby deprecation warnings. If there are any warnings, they should be fixed.
Next, you should build the ruby upgrade branch of the app to Integration, and manually test its features to ensure that the new Ruby version hasn’t broken the app.
It’s worth checking the logs for deprecation warnings at this point (and fixing them), in case there are warnings that weren’t flagged by the test suite run.
Next, check our monitoring tools, such as Grafana and Sentry.
The PR should be safe to merge.
Before the application will run with the new version, it will need to be restarted as well as deployed as normal. You can do this by running the deploy:with_hard_restart deploy task within the ‘Deploy App’ job in Jenkins.

NOTE If the application is deployed without being restarted (e.g via continuous deployment) you will need to manually restart. You can do this by running the app:hard_restart deploy task within the ‘Deploy App’ job in Jenkins.