Ryz Labs/Migrations/Legacy Rails to Rails 8
Migrations

Legacy Rails to Rails 8.1: Upgrade and Modernization Runbook

A staff-engineer runbook for moving an old Rails monolith to Rails 8.1 one minor at a time, with dual boot, a deprecation burn-down and packwerk boundaries.

Moving a legacy Rails monolith to Rails 8.1 means stepping through every minor release in order, dual-booting each next version in CI and production until the old one can be dropped, and pulling the codebase into a modular monolith while you go. Do not skip versions and do not rewrite. What decides success is whether the deprecation warnings go to zero on the current version before you bump to the next one.

Why teams migrate now

The Rails maintenance policy gives each minor series bug fixes for one year and security fixes for two years after its first release. After that, the policy says plainly that no new versions are released, so a vulnerability in an old series stays open in your app. As of November 20, 2026, the 8.0 series has dropped out: its security support ended on November 7, 2026. That leaves Rails 8.1 as the only series still getting fixes, with security support until October 10, 2027. Rails 8.1.4.1, a security release, shipped on November 4, 2026 (see the Rails blog). Anything older than 8.1 is no longer patched.

Ruby is on the same clock. The Ruby branch table lists 2.7 as end of life on March 31, 2023, 3.0 on April 23, 2024, 3.1 on March 26, 2025 and 3.2 on April 1, 2026. Ruby 3.3 gets security fixes only, with end of life expected March 31, 2027. Ruby 3.4 and Ruby 4.0 (released December 25, 2025) are in normal maintenance. A legacy app usually sits on an end-of-life Rails and an end-of-life Ruby together, and that compounds the problem: you can't move Ruby far without moving Rails, and your gems pin both.

The business side follows from that. A penetration test or SOC 2 auditor will flag an unsupported framework, and you have no patch to point to. Security fixes have to be backported by hand into a forked gem. Each year you wait, more gems stop releasing for the old Rails, so the eventual jump gets bigger. And senior Rails engineers will turn down a role that means maintaining a frozen stack.

Before you start: inventory and baseline

The strangler-fig plan, phase by phase

With Rails, the strangler fig works on two levels. In the short term, the new framework version takes over production one slice of traffic at a time through dual boot. In the long term, clean packages take over the tangled app/ directory one domain at a time.

Phase 0: Make the suite trustworthy and the warnings visible

Fix or quarantine flaky specs until a green build actually means something. Turn on deprecation reporting everywhere: in test, set config.active_support.deprecation to :raise, but only after you have a list of the existing warnings. Collect warnings from production logs as well, because code paths that tests never touch still emit them in production. Put the warning count on a dashboard. That number is your burn-down chart.

Exit criteria: the CI pass rate is stable, the warning inventory exists and is grouped by source file, and the baseline metrics are recorded.

Phase 1: Set up dual boot

Add a second Gemfile that resolves the next Rails minor. With the next_rails gem, this is a Gemfile.next symlink plus a NextRails.next? check in the Gemfile; Shopify's bootboot does the same with a Gemfile_next.lock and the DEPENDENCIES_NEXT environment variable. Then add a CI job that runs the full suite with BUNDLE_GEMFILE=Gemfile.next. Wrap version-specific code in a conditional on the next flag so one branch works on both versions. That way the upgrade lands in small pull requests on main instead of in a long-lived branch that diverges.

Exit criteria: both lockfiles resolve, the next-version CI job runs on every PR, and the failures are known and ticketed.

Phase 2: One minor at a time, warnings to zero each step

For each minor between your current version and 8.1, run the loop in the same order every time:

  1. Get the deprecation warnings on the current version to zero.
  2. Make the next-version CI job green.
  3. Run bin/rails app:update and review every config diff by hand.
  4. Ship the next version to a canary slice of production.
  5. Promote it, make it the primary Gemfile, and point Gemfile.next at the following minor.

Flip the new framework defaults in the generated new_framework_defaults initializer one at a time, and leave config.load_defaults behind until every flag is on. The flags that cause production incidents are the ones that change persisted formats: the cookie serializer (go to :hybrid before you go to :json), message encryptor and verifier settings, and the cache format version. Ruby upgrades get their own release. Bump Ruby within the range the current Rails supports, never in the same deploy as a Rails bump, and end on a Ruby series in normal maintenance (3.4 or 4.0 today) that your final Rails and gem set support.

Exit criteria per step: zero deprecation warnings on the current version, the next-version suite is green, the canary error rate and p95 match baseline, and the old lockfile is deleted.

Phase 3: Zeitwerk and dependency cleanup

If the app still runs the classic autoloader, move it to Zeitwerk as a phase of its own, before the version that requires it. Run bin/rails zeitwerk:check and fix whatever it reports. The usual causes are file names that don't match their constants, acronym inflections such as API or HTML (declare them with inflect.acronym), files in app/ that define several constants, and require_dependency calls you can now delete. Use this pass to remove dead gems, replace abandoned ones (protected_attributes becomes strong parameters, paperclip becomes Active Storage), and move vendored forks back to upstream releases.

Exit criteria: zeitwerk:check is clean, eager loading works in CI (config.eager_load = true in the test environment catches load-order bugs), and bundler-audit reports no known advisories.

Phase 4: Packwerk boundaries for a modular monolith

This is where an upgrade becomes modernization. Add Shopify's packwerk, then create packages under packs/ or components/ along the ownership lines you drew in the inventory: billing, accounts, catalog, notifications. Each package gets a package.yml that declares its dependencies and turns on privacy enforcement. Run bin/packwerk update-todo to record the existing violations as a todo file, then burn that file down the same way you burned down deprecations. New code may not add violations. Old violations shrink each sprint. Where a domain needs to be truly isolated, a Rails engine gives it its own routes, migrations and test suite without a network hop.

Exit criteria: the core domains are packages with owners, packwerk check runs in CI, and the violation count is trending down.

Phase 5: Jobs, infrastructure and the steady state

Move direct Sidekiq::Worker classes behind Active Job where it helps you, or make a deliberate choice to stay on native Sidekiq for its features. Either is fine. What matters is one documented path. Solid Queue, the Rails team's database-backed Active Job backend, is worth evaluating if you'd rather not run Redis just for jobs; benchmark it against your peak queue depth before you commit. Kamal, a deploy tool from the same ecosystem, ships containers to your own servers, and it's worth a look if the app runs on hand-built hosts today. Neither has to be part of the upgrade. Once you're on 8.1, schedule each future minor upgrade as routine maintenance and keep the dual-boot job in place.

Exit criteria: the app is on Rails 8.1 with a supported Ruby, the next-minor CI job is wired up, and the queue backend is documented with measured throughput.

PhaseGoalKey techniqueExit criteria
0. Trust the suiteGreen means greenQuarantine flakies, deprecation inventory, production log captureStable CI, warning count on a dashboard
1. Dual bootTest the next Rails on mainnext_rails Gemfile.next or bootboot, second CI jobNext-version suite runs on every PR
2. Minor by minorReach 8.1 without skippingWarnings to zero, app:update, framework defaults flipped one at a timeCanary matches baseline, old lockfile deleted
3. Zeitwerk and gemsModern loading, clean dependencieszeitwerk:check, inflections, gem replacement, bundler-auditEager load passes, no known advisories
4. PackwerkModular monolithpackage.yml boundaries, todo burn-down, engines where neededpackwerk check in CI, violations falling
5. Steady stateNever fall behind againActive Job path, queue backend choice, permanent dual bootSupported Rails and Ruby, next-minor job live

Cutover and rollback

A Rails upgrade cuts over by fleet, not by URL. Run the next-version boot on a canary group of web processes, starting with one pod or one host behind the load balancer, and send it a small weighted share of traffic. Keep Sidekiq workers on the old version until the web tier is promoted, then canary one worker pool per queue, beginning with low-risk queues. If you need more confidence on read-heavy endpoints, mirror a sample of GET requests to the canary and diff the response bodies against production. Normalize timestamps and CSRF tokens before you diff.

Go/no-go checklist for each step:

Rollback by phase. In Phases 1 and 2, roll back by pointing the canary back at the primary Gemfile, which is a redeploy or an environment-variable flip, and by draining its share in the load balancer. This only stays safe if every persisted-format flag was in a dual-read mode. A canary that wrote JSON-only cookies or a new cache format before you rolled back will log users out or poison the cache, so flip those flags in a separate later release. In Phase 3, revert the Zeitwerk or gem pull request, since nothing persisted changed. In Phase 4, packwerk changes are static checks, so roll back by reverting the package move. In Phase 5, a queue backend change needs both backends running while the old queues drain. Never cut over with jobs still sitting in the old backend.

Risk matrix

RiskLikelihoodImpactMitigationEarly warning signal
Abandoned gem blocks the next minorHighHighGem audit up front, replace or fork early, budget the replacement as its own ticketGemfile.next fails to resolve
Cookie serializer change logs users outMediumHighUse :hybrid first, keep it for a full session lifetime, then go to :jsonSpike in sign-in events or CSRF failures on the canary
Cache format change breaks rollbackMediumMediumFlip cache_format_version in its own release, namespace the cache per versionDeserialization errors in logs after a revert
Monkey patch silently stops applyingMediumHighCharacterization specs on the patched behavior, delete patches where upstream fixed itSpec passes but production output differs in shadow diffs
Zeitwerk naming errors only in productionMediumMediumzeitwerk:check in CI, eager_load in testNameError on the first request to a rarely used controller
Job payloads incompatible across versionsMediumHighPrimitive-only job arguments, canary workers per queue, drain before switchingRetry queue growth or dead-set entries
Deprecation burn-down stallsHighMediumOwner per warning group, :raise in test, count tracked weeklyFlat warning count for two sprints
Packwerk becomes a todo file nobody shrinksMediumLowNo new violations rule in CI, package owners report the countTodo file grows
Ruby and Rails bumped togetherLowHighSeparate releases, alwaysA PR that touches both .ruby-version and Rails

Typical team shape

This work is done by people who have taken Rails apps through several majors and know where they break. A workable shape:

Many teams begin with a pod of 3 to 5 senior engineers (a tech lead plus engineers), and a full pod is about seven. Ryz engineers on your team start from $7,000 per month (our published range is $7,000–$15,000 per engineer per month, mostly mid-level to senior), quoted per team. Project cost = team size × months × monthly rate, and the number of months depends on what your inventory turns up. Once you say go, engineers can typically start in under two weeks. Browse Ruby on Rails developers, see Rails developer rates, or scope your team with us.

Where an AI pod helps (and where it doesn't)

A lot of a Rails upgrade is repetitive, and that is where AI-assisted tooling speeds things up. Our AI pod uses coding assistants to draft request specs from routes and recorded production traffic, to group thousands of deprecation lines by root cause, to draft the mechanical pull requests (renaming files to match Zeitwerk constants, rewriting attr_accessible models to strong parameters, converting old finder syntax), and to sort shadow-diff output so a person only reads the real differences. Dependency bots such as Dependabot or Renovate open the gem bump PRs.

The judgment calls stay with people: which framework default to flip next, whether a monkey patch is still needed, and where a package boundary should go. Every AI-drafted change goes through human code review and has to pass the characterization specs and the dual-boot CI job before it merges. A codemod that compiles but changes a JSON key gets caught by the specs, not by trusting the tool.

When not to migrate (yet)

Ryz isn't the right fit if you want a management-consulting transformation program or a self-serve marketplace of hourly freelancers.

Related

FAQ

How long does a Rails upgrade to 8.1 take?

It depends on how many minor versions you have to cross, how many gems block each step, how many monkey patches touch Rails internals, how good your test coverage is, and whether you are also moving to Zeitwerk or a new asset pipeline. The gem audit and the deprecation inventory in Phase 0 give you the real scope. Any estimate made before them is a guess.

Can we skip straight from an old Rails version to Rails 8.1?

We don't recommend it. Each minor release deprecates behavior before the next one removes it, so skipping a version means losing the warning that would have told you what was about to break. Going one minor at a time with dual boot keeps each change small, testable and easy to roll back.

Do we need to freeze feature work during the upgrade?

No. Dual boot exists so feature teams can keep shipping on main while the next version runs in a second CI job. The one rule is that new code must not add deprecation warnings or packwerk violations, and CI enforces it.

Should we break the monolith into microservices instead?

Usually not as part of the upgrade. A modular monolith with packwerk boundaries gives you clear ownership and dependency rules without network calls, distributed transactions or a new deployment topology. If a package later proves it needs to scale on its own, its boundary is already drawn and extraction is far easier.

What does a Rails modernization cost?

Cost is team size multiplied by months multiplied by the monthly rate per engineer. The team size comes from how much parallel work the inventory shows, such as gem replacements, package extraction and test backfill. The months come from the number of version steps and the size of the warning burn-down.

Questions we didn't answer? Email info@ryzlabs.com.

Thanks — your message has been sent. We’ll get back to you soon.

Something went wrong while sending your message. Please try again or email info@ryzlabs.com.

Explore Ryz Labs

Software development servicesAI development companyIndustriesStaff augmentationAI pod teamsNearshore software developmentHire engineers by roleEngineer ratesGuidesBuyer guidesCase studiesHow we vet engineers

Ryz Labs

Senior engineers on your team. AI pod teams that ship.

Tell us what you're building. You get a scoped plan, a price and the names of the people who would do the work.

  • Only the top 1% of tens of thousands interviewed make it
  • On US business hours, including New York hours
  • Trusted by Fortune 500 engineering teams

Tell us who you need

A Ryz partner replies with a scoped team plan.

Start a conversation →

Prefer to talk? Book a 15-min call →