But now that 8.1 is stable, the real question for most developers is: how do I upgrade safely, and what’s actually new that will affect my daily workflow?
This post isn’t another list of Rails 8.1 headline features, you can read those in our earlier coverage. Instead, this is a practical guide for upgrading your app confidently, along with a few under-the-radar improvements that didn’t get the spotlight they deserved.
Step 1 - Prep Before You Upgrade
Upgrading Rails should never start with bundle update. The first step is making sure your app is in a healthy state.
- Update Ruby first - Rails 8.1 supports Ruby 3.3+. Get your runtime up-to-date before touching Rails.
- Run your test suite and fix anything that’s been quietly failing.
- Audit your gems, especially those that hook into Active Record, Active Job, or Railties. Run bundle outdated and take note of anything that hasn’t seen a release in a while.
Once things look stable, create a new branch and bump your Rails dependency:
gem "rails", "~> 8.1.0"
Then run:
bundle update rails rails app:update
Commit everything to a new branch and run your full test suite.
Step 2 - What’s Likely to Break (and How to Fix It)
If you’re upgrading from 8.0, most apps will upgrade cleanly. Still, there are a few subtle changes worth knowing about:
- Association Deprecations - Rails now lets you mark associations as deprecated. You’ll see warnings in your logs if older models use them. Don’t ignore these; they’ll become hard errors in future versions.
- Logging Output - if you parse text logs in production, structured event logging (Rails.event) might change your expected output. Update any regex-based log parsers or dashboards.
- Background Jobs - if you’re experimenting with Active Job continuations, remember that jobs must still be idempotent. Continuations save state, not side-effects.
If you hit issues, check the Rails 8.1 release notes and GitHub changelog - both list compatibility fixes and deprecations in detail.
Step 3 - 5 Hidden Features You Might’ve Missed
1. Association Deprecations
Active Record now supports deprecate_association, letting you flag associations that should be phased out.
class User < ApplicationRecord has_many :posts deprecate_association :posts end
This helps teams refactor safely without silently relying on legacy relationships. It’s particularly handy in large apps with mixed-age models.
2. Local CI Support
Rails 8.1 introduces Local CI, a new way to simulate continuous integration locally with bin/ci. It runs a full suite of checks, including tests, linting, and security audits, mimicking how your CI runs them in the cloud.
bin/ci
It’s small, simple, and makes local validation faster. Think of it as rails test plus linting discipline.
3. Markdown Rendering Goes Native
You can now render .md templates directly through Action View - no extra gems like Redcarpet or Kramdown needed.
Markdown has become the formatting language of AI, and with many Rails AI dev tools and LLMs generating Markdown output, this addition makes it far easier to serve AI-produced content directly in your Rails app - from documentation to dynamic blog content.
4. Credential Fetching for Deployments
Deploying with Kamal or Capistrano? Rails 8.1 introduces native credential fetching, letting you securely pull secrets from config/credentials.yml.enc instead of environment variables.
bin/rails credentials:fetch
It’s a small step, but it simplifies DevOps setup and keeps your secrets centralised where they belong.
5. Structured Event Logging
The new Rails.event API brings structured, JSON-style logging to the framework:
Rails.event "user_signup", user_id: current_user.id, plan: current_user.plan
Clean logs, machine-readable output, and better integration with monitoring platforms - without third-party gems.
Step 4 - Post-Upgrade Checklist
Once you’ve upgraded and run your tests:
- Check your logs for deprecations (grep DEPRECATION works wonders).
- Test background jobs and ensure long-running ones behave correctly.
- Re-run your CI locally using bin/ci.
- Deploy to staging with Kamal and confirm credential fetching works.
If everything holds up there, you’re ready for production.
Step 5 - Looking Beyond 8.1
Rails 8.1 feels like a grown-up release, one that smooths rough edges rather than adds flash. But it also lays groundwork for what’s next.
Expect Rails 8.2 to expand on job reliability, tighten observability, and improve default Hotwire setups. And with AI tools becoming part of everyday development, Rails is already making subtle moves (like Markdown rendering) that quietly prepare the framework for that future.