Introduction

Upgrading Rails shouldn’t feel risky. This guide shows a small-steps, reversible approach to get to Rails 8 + Ruby 3.3 with confidence—no big-bang refactors, minimal downtime.

Why Upgrade Now

• Security fixes and modern defaults reduce platform risk
• Ruby 3.3 performance improvements and better memory behaviour
• Cleaner APIs, easier onboarding, and healthier dependency graph

Business Outcomes

• Fewer production incidents and clearer deprecation paths
• Faster CI and deploys; smaller containers
• Happier devs and faster feature throughput

1) Prep Work (1–2 Days)

• Freeze prod and tag a baseline; create an upgrade branch
• Turn on deprecation warnings in CI
• Audit gems: note blockers and alternatives
• Add smoke tests (auth, checkout, critical flows) if coverage is thin

2) Dual‑Boot Strategy (Document the Diff)

Treat rails app:update as documentation. Adopt a toggle to run old/new configs side by side until you’re confident.

# Gemfile
ruby "3.3.0"
gem "rails", "~> 8.0"
# Use ENV["RAILS_NEXT"] to switch conditional config while migrating

# Keep new defaults under config/, then adopt gradually
bin/rails app:update  # review diffs; commit in small PRs

3) Ruby 3.3 First

• Bump Ruby and pin CI to it; address native gem warnings early
• Update Docker base images; avoid x86/ARM mismatch with BUNDLE_FORCE_RUBY_PLATFORM=true if needed
• Rebuild images; ensure prod and CI match

4) Chip Away at Breakages

• Replace removed APIs and flipped defaults; update generators/initializers
• Remove monkey patches that Rails 8 makes obsolete
• Update encrypted credentials via bin/rails credentials:edit

5) Shipping Without Fear

• Feature flags for risky changes
• Blue/green or canary deploys for the upgrade
• Watch p95/p99 latency, error rate, and background job throughput
• Keep a rollback.md with exact steps to revert

6) Post‑Upgrade Wins

• Enable boot caching and verify Zeitwerk eager load
• Align on new defaults (cookies/CSRF, headers, etc.)
• Retune Sidekiq/queuing concurrency; audit crons

Checklist

• Ruby 3.3 in CI and production
• Rails 8 with dual‑boot removed
• All gems updated or replaced
• Smoke tests green; error rate steady
• Backups/rollbacks verified

Conclusion

Upgrades are a product investment. By shipping in small, safe steps—Ruby first, then Rails—you reduce risk and unlock platform velocity. Need a hand planning or executing a zero‑downtime upgrade? We’re happy to help.

Written by Ahmad
Ahmad Hassan, Senior Ruby on Rails expert with 10+ years of experience. He builds web and mobile applications using React, Next.js, and TypeScript, and contributes to backend development using Python and Ruby on Rails.