Rails update guidelines
We strive to run GitLab using the latest Rails releases to benefit from performance, security updates, and new features.
Rails update approach
- Prepare an MR for GitLab.
- Prepare an MR for Gitaly.
- Create patch releases and backports for security patches.
Prepare an MR for GitLab
- Check the Upgrading Ruby on Rails guide and prepare the application for the upcoming changes.
- Update the
railsgem version in
bundle update rails.
- Run the update task
- Update the
bundle update --conservative activesupportin the
- Resolve any Bundler conflicts.
- Ensure that
@rails/actioncablenpm packages match the new rails version in
- Create an MR with the
pipeline:run-all-rspeclabel and see if pipeline breaks.
- To resolve and debug spec failures use
git bisectagainst the rails repository. See the debugging section below.
- Include links to the Gem diffs between the two versions in the merge request description. For example, this is the gem diff for
activesupport22.214.171.124 to 126.96.36.199.
Prepare an MR for Gitaly
- Update the
activesupportgem version in Gitaly Ruby's Gemfile.
bundle update --conservative activesupport.
- Create an MR against the Gitaly project with these changes.
- Make this MR dependent on the MR created in the GitLab project.
- Merged this MR only after merging the GitLab project's MR.
Create patch releases and backports for security patches
If the Rails update was over a patch release and it contains important security fixes, make sure to release it in a GitLab patch release to self-managed customers. Consult with our release managers for how to proceed.
We also log Ruby and Rails deprecation warnings into a dedicated log file,
log/deprecation_json.log. It provides
clues when there is code that is not adequately covered by tests and hence would slip past
For GitLab SaaS, GitLab team members can inspect these log events in Kibana (
Git bisect against Rails
Usually, if you know which Rails change caused the spec to fail, it adds additional context and
helps to find the fix for the failure.
To efficiently and quickly find which Rails change caused the spec failure you can use the
git bisect command against the Rails repository:
railsproject in a folder of your choice. For example, it might be the GDK root dir:
cd <GDK_FOLDER> git clone https://github.com/rails/rails.git
gem 'rails'line in GitLab
gem 'rails', ENV['RAILS_VERSION'], path: ENV['RAILS_FOLDER']
RAILS_FOLDERenvironment variable with the folder you cloned Rails into:
Change the directory to
RAILS_FOLDERand set the range for the
cd $RAILS_FOLDER git bisect start <NEW_VERSION_TAG> <OLD_VERSION_TAG>
<NEW_VERSION_TAG>is the tag where the spec is red and
<OLD_VERSION_TAG>is the one with the green spec. For example,
git bisect start v188.8.131.52 v184.108.40.206if we're upgrading from version 220.127.116.11 to 18.104.22.168. Replace
<NEW_VERSION_TAG>with the tag where the spec is red and
<OLD_VERSION_TAG>with the one with the green spec. For example,
git bisect start v22.214.171.124 v126.96.36.199if we're upgrading from version 188.8.131.52 to 184.108.40.206. In the output, you can see how many steps approximately it takes to find the commit.
git bisectprocess and pass spec's filenames to
scripts/rails-update-bisectas arguments. It can be faster to pick only one example instead of an entire spec file.
git bisect run <GDK_FOLDER>/gitlab/scripts/rails-update-bisect spec/models/ability_spec.rb # OR git bisect run <GDK_FOLDER>/gitlab/scripts/rails-update-bisect spec/models/ability_spec.rb:7
When the process is completed,
git bisectprints the commit hash, which you can use to find the corresponding MR in the
git bisect resetto exit the
Revert the changes to
git checkout -- Gemfile