Rails 8.1 Upgrade Assessment

Date: 2026-07-24 Repository revision assessed: 56e72eff8d67

Executive conclusion

Chatwoot should target Rails 8.1.3, but it should not jump from Rails 7.1 to 8.1 in one compatibility change or one production deployment.

The implementation sequence is:

1. Refresh the existing Rails upgrade PR on the latest develop and move to Rails 7.2.3.1 while retaining Rails 7.0 framework defaults.
2. Upgrade to Rails 8.0.5 in a stacked PR.
3. Upgrade to Rails 8.1.3 in a second stacked PR.
4. Enable the accumulated Rails 7.1, 7.2, 8.0, and 8.1 defaults in separately deployable risk groups.

Rails itself recommends upgrading one minor version at a time because minor versions may change public APIs and each intermediate release provides the useful deprecation warnings. It also recommends enabling new framework defaults gradually. See the official Rails upgrade guide.

The distinction is:

• Direct-to-8.1 as the final target: yes.
• A direct 7.1-to-8.1 implementation and rollout: no.
• Stopping on Rails 7.2: no. Rails 7.2.0 was released on 2024-08-09 and Rails security support lasts two years, so the 7.2 series reaches security end of life on 2026-08-09. It is a short-lived compatibility checkpoint, not a useful long-term destination. See the Rails maintenance policy.

As of this assessment, the current releases are Rails 7.1.6, 7.2.3.1, 8.0.5, and 8.1.3. See Rails versions on RubyGems.

Applying the published one-year bug-fix and two-year security windows to each series' initial release date gives:

Current Chatwoot baseline

Two defaults-sensitive surfaces are particularly important:

• Chatwoot declares 19 encrypted attributes across 13 OSS and Enterprise files.
• Chatwoot has 166 perform_later/deliver_later call sites; 14 files contain both transaction and enqueue behavior.

What the compatibility experiments showed

The assessment used isolated copies of this exact revision, changed only dependency constraints and the minimum code necessary to boot, and did not modify the application worktree.

Rails 7.2.3.1

• Bundler resolved Rails 7.2.3.1.
• The only definite application-code incompatibility found is User using alias_attribute to alias an association:
  • app/models/user.rb: alias_attribute :conversations, :assigned_conversations
  • Rails 7.2 treats alias_attribute as a database-attribute facility. This should become an explicit method or alias_method.
• administrate-field-belongs_to_search must move from 0.9.0 to 0.10.0 because 0.9.0 constrains Rails to < 7.2.
• Updating jbuilder and debug during this checkpoint removes failures that otherwise surface later:
  • Jbuilder 2.11.5 uses ActiveSupport::ProxyObject, which Rails 8 removes.
  • Debug 1.8.0 fails in the current Ruby 3.4 toolchain while running the Rails update task.
• The first live worker boot exposed an unsafe resolver result: Sidekiq 7.3.1 accepts connection_pool >= 2.3, so Bundler selected 3.0.2, but both Sidekiq scheduler threads then crashed because 7.3.1 calls the removed positional TimedStack#pop API. Sidekiq 7.3.10 explicitly constrains connection_pool < 3; that exact worker line and connection_pool 2.5.5 are required for this checkpoint.
• Rack Mini Profiler 3.2.0 references the removed Rack::File constant under Rack 3.2. Updating it to 4.0.1 restores its JavaScript endpoint.
• Rails' Active Storage install task tried to generate three migrations, but Chatwoot's initial schema migration and current schema.rb already contain service_name, variant records, and a nullable checksum. Those generated migrations must not be copied blindly.

Rails 8.1.3

The initial dependency resolution failed for three independent reasons:

1. Chatwoot's devise-secure_password fork constrains Railties to < 8.
2. administrate-field-belongs_to_search 0.10.0 constrains Rails to < 8 and Administrate to < 1.
3. rails-i18n ~> 7.0 constrains Railties to < 8.

After locally relaxing the two fork constraints, selecting Rails-compatible dependency versions, and making the minimum code changes:

• bin/rails zeitwerk:check passed on Rails 8.1.3.
• This required changes to 35 existing main-repository files:
  • Gemfile and Gemfile.lock
  • 31 model files using removed enum keyword syntax
  • the custom schema dumper initializer
  • the singular app route
• The Rails 7.2 User association alias fix raises the known floor to 36 files.
• This boot result does not prove production readiness. It deliberately did not solve Azure support, activate new defaults, run the complete test matrix, or add the required regression specs.

The resolved Rails 8.1 graph also required or selected these application-level changes:

The current, Rails 7.2, and experimental Rails 8.1 lock graphs all passed bundle-audit against the advisory database updated on 2026-07-22. That does not replace a release-time audit.

File-impact estimate

These estimates are for tracked files in the Chatwoot repository. Any remaining companion dependency work is listed separately.

The sequential route does not materially reduce the final total number of changed files. It changes when and how those files are changed:

• Rails 7.2 isolates the association and dependency compatibility issues.
• Rails 8.0 isolates removed APIs and the Administrate/Sprockets transition.
• Rails 8.1 isolates Azure removal and request/job/time behavior.
• Each checkpoint can be deployed and rolled back before a serializer or encryption default becomes irreversible.

bin/rails app:update --pretend reported 26 config/bin/public actions for Rails 7.2 and 32 for Rails 8.1, in addition to attempted migrations. Those are candidate generator changes, not a recommended diff. Accepting them wholesale would overwrite or churn Chatwoot-specific Vite, Sprockets, environment, deployment, and initializer choices.

Changed interfaces and Chatwoot impact

Defaults Chatwoot has not yet activated

Because config.load_defaults is still 7.0, upgrading the gem alone and activating defaults are different operations.

An AST scan found no explicit return, break, or throw inside Chatwoot transaction blocks, so Rails 7.2's changed non-local-return transaction behavior has no direct syntax hit in the current app. Keep a runtime audit for gem and dynamically composed behavior.

Rails 7.2 interface changes

See the official Rails 7.2 release notes and upgrade guide.

Rails 8.0 interface changes

See the official Rails 8.0 release notes.

Rails 8.1 interface changes

See the official Rails 8.1 release notes.

Removed interfaces audited without a direct application hit

The repository scan also checked the principal removed interfaces that do not currently require an application edit:

Highest-risk break scenarios

Prerequisites and migration decisions

The following work must happen before Rails 8.1 can be considered releasable:

1. Choose the Azure policy.

   • Preserve Azure by extracting/maintaining an ActiveStorage::Service adapter, or
   • announce deprecation and supply a verified blob migration path to S3/GCS.
   • This decision changes product support and must not be inferred during implementation.

2. Prepare the Rails-constrained Admin dependency.

   • devise-secure_password is resolved by moving to upstream 2.2.1 in the Rails 7.2 checkpoint.
   • Replace, upstream, or maintain a Rails 8/Administrate 1-compatible administrate-field-belongs_to_search.

3. Inventory encrypted production data.

   • Count rows by model and encrypted attribute.
   • Prove all values decrypt under the transition configuration.
   • Prove deterministic queries still return the same records.
   • Define the re-encryption batch, retry, audit, and rollback procedure.

4. Define rolling-deploy compatibility.

   • Pin cache, message, cookie, and encryption formats during version-only deploys.
   • Test old and new application processes against the same Redis, database, jobs, and cookies.
   • Enable each new write format only after old processes cannot return.

5. Make the Super Admin asset ownership explicit.

   • Either declare and retain Sprockets or migrate those assets in a separate project.
   • Do not let an Administrate dependency update silently choose the asset architecture.

6. Reconcile Active Storage migration history.

   • Verify every supported installation has the service_name, variant record, and nullable checksum changes even though the squashed initial migration already has them.
   • Add idempotent corrective migrations only if real supported installations are missing them.

7. Add upgrade observability.

   • Fail CI on new Rails deprecations after an allowlist is baselined.
   • Add dashboards/alerts for job failures and latency, session/auth failures, Active Storage errors, request 4xx/5xx, database errors, and cache hit rate.

Dependency-ordered implementation plan

Each milestone should be independently green and revertible. Framework defaults and serialized write formats should not change in the same deployment as the Rails gem version.

Milestone 0: Guardrails and dependency unblockers

R0.1 — Establish the upgrade CI lane (S)

• Files: CI configuration, deprecation configuration, and a small boot/contract spec.
• Work: Run the current suite with deprecations captured; add zeitwerk:check, production boot, assets, fresh schema load, and bundle-audit.
• Acceptance: Current Rails 7.1.5.2 is green; known deprecations are recorded with owners; newly introduced deprecations fail the upgrade lane.
• Verify: Full OSS and Enterprise RSpec suites, targeted frontend build, RuboCop for changed Ruby files, production asset precompile, and fresh PostgreSQL schema load.
• Depends on: None.

R0.2 — Move devise-secure_password to upstream 2.2.1 (S)

• Work: Replace the inaccessible Chatwoot fork with the exact upstream release supporting Devise 4 and Railties 8; validate password policy, Devise callbacks, authentication, and MFA.
• Acceptance: Upstream 2.2.1 is locked and the authentication/MFA matrix passes on every checkpoint.
• Depends on: R0.1.

R0.3 — Resolve the Administrate search field dependency (M, companion repository)

• Work: Upstream, fork, or replace the field for Administrate 1/Rails 8; verify its search query, form, display, and authorization behavior.
• Acceptance: Versioned dependency compatible with both the Rails 7.2 checkpoint and Administrate 1; Super Admin contract tests pass.
• Depends on: R0.1.

R0.4 — Decide and prototype Azure support (M)

• Work: Select preserved-adapter or migration/deprecation path; prototype the chosen option against upload/download/direct-upload/variant/purge operations.
• Acceptance: Written product decision and a passing proof of concept. Rails 8.1 is blocked until this is complete.
• Depends on: None.

Milestone 1: Reach Rails 7.2 safely

R1.1 — Resolve Rails 7.2 dependencies and association alias (M)

• Files: Gemfile, Gemfile.lock, app/models/user.rb, focused dependency/user specs.
• Work: Upgrade Rails to 7.2.3.1, select administrate-field-belongs_to_search 0.10.0, update Jbuilder/debug, and replace the association alias_attribute.
• Acceptance: Rails reports 7.2.3.1; defaults remain 7.0; user conversation APIs are unchanged; no unexpected lockfile upgrades.
• Verify: User model/request specs, authentication specs, Admin specs, full suite, zeitwerk:check, asset builds, and advisory audit.
• Depends on: R0.1 and a compatible result from R0.3.

R1.2 — Validate data, jobs, and supported databases on 7.2 (M)

• Files: Focused request/job/storage/reporting specs and CI matrix only.
• Work: Test Active Job adapter behavior, transaction boundaries, PostgreSQL date handling, migration timestamp validation, WebP variants, upgraded database, and fresh database.
• Acceptance: No job observes uncommitted data; rollback suppresses side effects; schema and reports match the 7.1 baseline.
• Depends on: R1.1.

Deployment checkpoint: Deploy Rails 7.2.3.1 with 7.0 defaults, canary it, and prove rollback to 7.1.6.

Milestone 2: Catch up Rails 7.1 and 7.2 defaults

R2.1 — Migrate encryption and serialized formats (M)

• Files: Framework-default initializer/config, encryption service or runner if needed, and encryption/cache/signature specs.
• Work: Pin transition settings; run decrypt/deterministic-query inventory; re-encrypt if required; then enable cache and message formats in separate deploys.
• Acceptance: Old ciphertext, cookies, signed IDs, cached values, and jobs remain readable through the rolling-deploy window; rollback procedure is exercised.
• Depends on: R1.2.

R2.2 — Enable model, callback, parser, and job defaults (M)

• Files: Defaults initializer plus focused model, callback, message-rendering, and job specs.
• Work: Enable remaining 7.1 defaults in small groups, then 7.2 defaults; keep any intentionally retained old setting documented.
• Acceptance: config.load_defaults 7.2 is possible without an unexplained compatibility override; all product contracts remain stable.
• Depends on: R2.1.

Deployment checkpoint: Run Rails 7.2 with 7.2 defaults before beginning Rails 8 removal work.

Milestone 3: Remove Rails 8.0 incompatibilities

The enum rewrite should be split into four syntax-only tasks so review can verify value mappings:

R3.1a — Conversation and messaging enums (S)

• Files: conversation, message, attachment, contact, inbox, webhook, notification, and notification_subscription.
• Acceptance: Every mapping and generated predicate/scope is identical before and after.
• Depends on: R2.2.

R3.1b — Accounts, channels, bots, and integrations enums (S)

• Files: user, account_user, agent_bot, agent_bot_inbox, assignment_policy, integrations/hook, channel/twilio_sms, and channel/web_widget.
• Acceptance: Same as R3.1a, including deterministic encrypted integration behavior.
• Depends on: R2.2.

R3.1c — Content, import, campaign, and filter enums (S)

• Files: article, data_import, data_import_item, custom_filter, custom_attribute_definition, campaign, and macro.
• Acceptance: Same as R3.1a; import and campaign jobs preserve values and scopes.
• Depends on: R2.2.

R3.1d — Enterprise enums (S)

• Files: Eight Enterprise model/concern files found by the audit.
• Acceptance: Enterprise mappings, policies, Captain flows, SLA behavior, and Copilot message behavior are unchanged.
• Depends on: R2.2.

R3.2 — Upgrade Administrate and own the asset pipeline (M)

• Files: Dependency files, asset manifest/config if needed, Super Admin views/fields only where Administrate 1 requires it, and Admin specs.
• Work: Upgrade Administrate to 1.0, make sprockets-rails explicit, integrate R0.3, and preserve Vite for the dashboard.
• Acceptance: Production assets precompile; every Super Admin CRUD screen loads CSS/JS and custom fields; no dashboard asset regression.
• Depends on: R0.3, R3.1 tasks.

R3.3 — Replace removed/internal Rails APIs (S)

• Files: Schema dumper initializer, route compatibility only if needed on 8.0, and focused schema/route specs.
• Work: Remove or rebase the PostgreSQL schema dumper patch; upgrade Jbuilder; prove there are no remaining removed API calls.
• Acceptance: zeitwerk:check, schema dump/load, and route compilation pass on both Rails 7.2 and 8.0.
• Depends on: R3.1 tasks.

R3.4 — Upgrade to Rails 8.0.5 (M)

• Files: Dependency files plus narrowly required config/spec updates.
• Work: Update Rails, Administrate-related dependencies, Audited, Hairtrigger, Rails I18n, and compatible supporting gems. Keep Sidekiq 7.3 and existing runtime architecture.
• Acceptance: Rails 8.0.5 boots in production mode; 7.2 defaults remain explicit; OSS/Enterprise suites and product smokes pass.
• Depends on: R0.2, R3.2, R3.3.

Deployment checkpoint: Deploy Rails 8.0.5 and observe it before removing Azure or activating Rails 8 defaults.

Milestone 4: Reach Rails 8.1

R4.1 — Complete the Azure storage migration/adapter (M)

• Files: Adapter/config/migration runner and storage contract specs, according to R0.4.
• Acceptance: Every supported storage service passes upload, download, direct upload, variant, mirror if applicable, delete, and purge tests; customer rollback/migration procedure is documented.
• Depends on: R0.4, R3.4.

R4.2 — Migrate Rails 8.1 routes and request contracts (M)

• Files: config/routes.rb plus route/request/webhook/OAuth specs.
• Work: Replace the singular-resource index route, compare route tables, and test legacy query syntax exposure.
• Acceptance: Existing frontend URLs and helpers are unchanged; any unsupported third-party query syntax has an explicit migration decision.
• Depends on: R3.4.

R4.3 — Update Rails 8.1 dependencies and job adapter (M)

• Files: Dependency files, job config, and focused auth/job specs.
• Work: Update Rails I18n, acts-as-taggable-on, Devise Two Factor, Devise Token Auth, Bullet, and Sidekiq within 7.3.x; verify Sidekiq supplies the adapter.
• Acceptance: Authentication, OTP, tokens, tags, retries, cron, mail, and transaction timing pass; no Rails built-in Sidekiq adapter warning.
• Depends on: R0.2, R3.4.

R4.4 — Upgrade to Rails 8.1.3 (M)

• Files: Dependency files, time call sites if behavior requires an explicit conversion, schema dumper, and focused specs.
• Work: Take Rails 8.1.3, verify time semantics, allow the intentional schema sort in an isolated commit, and resolve app-owned deprecations.
• Acceptance: Production boot, zeitwerk:check, full OSS/Enterprise suites, asset builds, fresh/upgrade database paths, all storage services, auth, jobs, Action Cable, mailboxes, APIs, webhooks, and reporting smokes pass.
• Depends on: R4.1, R4.2, R4.3.

Deployment checkpoint: Canary Rails 8.1.3 with prior defaults and serialized formats. Prove rollback to Rails 8.0.5.

Milestone 5: Activate Rails 8 defaults and close the migration

R5.1 — Enable Rails 8.0 defaults (S)

• Work: Enable each 8.0 default, including regex timeout and freshness behavior, with targeted tests.
• Acceptance: config.load_defaults 8.0 is possible with documented exceptions only.
• Depends on: Stable R4.4 production checkpoint.

R5.2 — Enable Rails 8.1 defaults (M)

• Work: Enable relative-redirect enforcement, JSON escaping changes, view tracker changes, required-column ordering checks, and remaining defaults in separate risk groups.
• Acceptance: API snapshots, redirects, views, forms, and query behavior are intentionally accepted; config.load_defaults 8.1 is active.
• Depends on: R5.1.

R5.3 — Remove transition compatibility and finish observability window (S)

• Work: Remove encryption/serializer dual-read settings only after the rollback window expires; close the deprecation allowlist; capture operational results.
• Acceptance: No unexplained Rails deprecations; no old processes/data require transition settings; runbook and support notes are complete.
• Depends on: Stable R5.2 deployment.

Verification matrix

Every Rails-version checkpoint should run:

eval "$(rbenv init -)"
bundle check
bundle exec rails runner 'puts Rails.version'
bundle exec rails zeitwerk:check
bundle exec bundle-audit check --update
bundle exec rspec
bundle exec rubocop <changed-ruby-files>
pnpm build

It should also run production-mode boot and asset precompile using CI-safe secrets, plus:

• Fresh PostgreSQL database creation from schema.rb.
• Upgrade of a scrubbed production-like database with realistic encrypted data.
• Redis shared between old/new app and Sidekiq processes.
• Mixed-version rolling deploy and rollback.
• Disk, S3, GCS, and Azure-or-replacement Active Storage contracts.
• Agent login, API token, OTP, password policy/history, OAuth, and signed-link fixtures.
• Inbox message creation through API, email, supported social channels, and webhook delivery.
• Sidekiq immediate, scheduled, retry, cron, mail, and transaction-boundary jobs.
• Action Cable/WebSocket updates and notification fan-out.
• Super Admin CRUD and custom field browser smoke tests.
• Reporting across UTC, a non-UTC zone, and a DST transition.
• Enterprise-enabled suite and Captain/SLA/Copilot smokes.

Rollout and rollback rules

• Never combine a Rails minor-version change with a new cache/message/encryption write format.
• Keep database changes expand/contract compatible with the previous deployed Rails version.
• Do not remove old serializer/encryption readers until all old workers, web processes, cached values, queued jobs, and rollback windows are gone.
• Canary web and worker processes separately; a healthy web boot does not prove Active Job compatibility.
• Preserve Rails 8.0.5 as the immediate rollback target for the Rails 8.1 deployment.
• Treat Azure service errors, decrypt failures, auth failure-rate increases, Sidekiq retry growth, and schema drift as rollout blockers rather than post-release cleanup.

Scope deliberately excluded

The Rails migration should not also introduce:

• Propshaft migration for the dashboard or Super Admin.
• Solid Queue, Solid Cache, or Solid Cable.
• Sidekiq 8.
• A different Ruby version.
• Authentication architecture replacement.
• Redis topology changes.
• Unrelated Rails generator changes.

Each may be valuable later, but coupling them to the framework upgrade removes the ability to attribute and safely roll back failures.

Final recommendation

Start the work now with Rails 8.1.3 as the declared target and Rails 7.2.3.1/8.0.5 as required deployable checkpoints. Rails 7.2 is too close to security end of life to justify a separate long-term upgrade project, but skipping it would discard the exact deprecation and isolation boundary Rails provides.

The critical path is not the 31 mechanical enum edits. It is:

1. Azure Active Storage support.
2. The Rails-constrained Administrate search-field dependency.
3. Encrypted-data and serialized-format compatibility across rolling deploys.
4. Administrate 1 plus explicit Sprockets ownership.
5. Job timing and Sidekiq adapter verification.

Once those are settled, the remaining Rails 8 code changes are bounded and the isolated Rails 8.1 boot proves the application can reach the target without a broad rewrite.