moreminimore-chat/docs/rails_upgrade_assessment.md

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:

Series	Role in this plan	Bug-fix support through	Security support through
Rails 7.2	Short compatibility checkpoint	2025-08-09, already ended	2026-08-09
Rails 8.0	Short compatibility/rollback checkpoint	2025-11-07, already ended	2026-11-07
Rails 8.1	Target	2026-10-22	2027-10-22

Current Chatwoot baseline

Area	Current state	Consequence
Ruby	3.4.4	Already satisfies Rails 7.2 and Rails 8.x. Do not combine another Ruby upgrade with this work.
Rails	~> 7.1, locked at 7.1.5.2	Four minor-version checkpoints remain: current 7.1 patch, 7.2, 8.0, and 8.1.
Framework defaults	config.load_defaults 7.0	The project is on Rails 7.1 code with Rails 7.0 behavior. Defaults migration is a separate body of work.
Initializers	47 files	Several defaults and framework integrations are explicitly customized.
Application models	109 files	Active Record changes have a broad possible blast radius.
Application jobs	86 files	Active Job and transaction timing changes need representative integration tests.
Controllers	185 files	Routing, redirects, query parsing, cookies, and response serialization need smoke coverage.
Specs	796 total, including 234 Enterprise specs	The existing suite is substantial, but upgrade-specific contract tests are still needed.
Enterprise overlay	427 files under enterprise/app	Eight of the known Rails 8 enum changes are in Enterprise code.
Asset stacks	Vite plus Sprockets-backed Super Admin assets	Rails 8 new-app defaults must not be applied mechanically.
File storage	Local/S3/GCS plus the Rails Azure service	Rails 8.1 removes the built-in Azure service.

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:

Dependency	Current	Resolved Rails 8.1-compatible line	Why it changes
administrate	0.20.1	1.0.0	0.20.x requires Rails < 8; Super Admin compatibility and assets must be tested.
administrate-field-belongs_to_search	0.9.0	Custom/upstream-compatible release	0.10.0 still requires Rails < 8 and Administrate < 1.
devise-secure_password	Chatwoot fork	Upstream 2.2.1	This is the latest upstream release supporting Devise 4 while allowing Railties 8; 2.2.3 requires Devise 5.
rails-i18n	7.0.10	8.1.0	The 7.x line requires Railties < 8.
jbuilder	2.11.5	2.15.1	Current version uses removed ActiveSupport::ProxyObject.
acts-as-taggable-on	12.0.0	13.0.0	Version 12 does not allow Active Record 8.1.
audited	5.4.1	5.8.0	Current constraint does not cover Rails 8.
hairtrigger	1.0.0	1.3.1	Current constraint does not cover Active Record 8.
devise-two-factor	6.1.0	6.4.0	Current constraint stops below Rails 8.1.
devise_token_auth	1.2.5	1.2.6	Current constraint stops below Rails 8.1.
bullet	8.0.7	8.1.3	Current version rejects Active Record 8.1 at runtime.
sidekiq	7.3.1	7.3.10 with connection_pool 2.5.5	Sidekiq 7.3.1 crashes its schedulers with connection_pool 3. Sidekiq 7.3.10 encodes the safe < 3 constraint. Rails 8.1 also deprecates its built-in adapter in favor of Sidekiq's adapter, so avoid a simultaneous Sidekiq 8 migration.
sprockets-rails	Transitive	Explicit dependency, 3.5.x	Administrate 1 no longer supplies the transitive dependency, but Chatwoot Super Admin still uses Sprockets.
debug	1.8.0	1.11.1	Required for the current Ruby/Rails update tooling to run cleanly.

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.

Path	Exact known minimum	Production-ready estimate	Explanation
Rails 7.2.3.1, version compatibility only	3	3–5	Gemfile, Gemfile.lock, and the User association alias.
Refreshed existing Rails 7.2 PR	22	22	Also carries Rails-7.2 boundary fixes, Azure adapter replacement, Sidekiq scheduler and profiler compatibility, test stabilization, a production preflight, and the migration guide.
Rails 7.2.3.1 plus staged 7.1/7.2 defaults	3	8–15	Adds explicit defaults, encryption/serialization guards, and focused regression specs.
Rails 8.1.3, minimum boot floor from 7.1	36	At least 36	31 enum files, two dependency files, User, routes, and schema dumper.
Rails 8.1.3, production-ready	36	50–70	Adds Azure strategy, Super Admin asset fixes, defaults, job/auth/storage/request specs, schema validation, and rollout configuration.
External companion repositories	1 repository	Approximately 2–4 files	Only a fork/replacement of administrate-field-belongs_to_search remains; devise-secure_password is resolved upstream.

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.

Interface/default	Change	Chatwoot exposure	Required action
Active Record encryption digest	Rails 7.1 changes key derivation/digest behavior and disables SHA-1 support for affected legacy ciphertext by default.	19 encrypted declarations, including inbox/channel credentials, integration tokens, OTP secrets, webhook secrets, and Enterprise Twilio credentials.	Pin legacy-readable behavior first, inventory/decrypt all affected records, test deterministic lookups, rewrite ciphertext if needed, then flip the default in a later deploy.
Cache serialization	Rails 7.1 introduces format 7.1.	Redis cache and rolling application deploys.	Keep the old write format during the version deploy, then enable the new format after every old process is gone. Treat rollback compatibility as an acceptance criterion.
Message serialization/metadata	Rails 7.1 moves to newer serializers and optimized metadata.	Signed IDs, Active Storage IDs, OAuth account signed IDs, Warden/session-adjacent signatures, and any persisted messages.	Explicitly pin on the first deploy; validate old tokens and signatures; enable separately.
Callback ordering	Rails 7.1 changes callback execution defaults.	Message creation, notifications, webhooks, emails, imports, and auditing rely heavily on callbacks.	Add ordering assertions around side effects and enable separately from the version bump.
Attribute/association validation	Rails 7.1 changes readonly-attribute and belongs-to foreign-key validation defaults.	High model count and Enterprise extensions.	Run the complete model/request suite and inspect new validation errors before enabling.
Test exception handling	Rails 7.1 replaces boolean show_exceptions values with :all, :rescuable, and :none.	config/environments/test.rb still sets true.	Replace it with the intentional symbolic mode and re-run controller/request exception specs.
HTML parsing/sanitization	Rails 7.1 defaults use HTML5 variants.	Email/message rendering, Help Center content, and Action Text.	Run content fixtures through sanitizer and rendering regression tests.
Enqueue after transaction commit	Rails 7.2 changes the standard job/transaction integration.	166 enqueue/delivery calls and 14 files combining transactions and enqueueing.	Verify jobs never observe uncommitted/missing data and that rollback does not enqueue side effects.
PostgreSQL date decoding and migration timestamps	Rails 7.2 changes decoding and validates migration timestamps.	Reporting, imports, schema setup, and old migration history.	Run reporting/import specs and validate both existing-database and fresh-database setup.

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

Interface	Repo finding	Migration
alias_attribute	User aliases conversations to an association.	Replace with an explicit delegating method or alias_method; add a user association spec.
Active Job test adapter selection	Tests now consistently respect configured queue_adapter.	Ensure test config uses the test adapter where matcher semantics require it; run job and mailer specs.
Framework defaults	Enqueue timing, Active Storage WebP behavior, PostgreSQL date decoding, migration timestamp validation, and YJIT defaults become available.	Activate one risk group at a time after the Rails 7.2 code deploy.

See the official Rails 7.2 release notes and upgrade guide.

Rails 8.0 interface changes

Interface	Repo finding	Migration
Enum declaration	Rails 8 removes keyword-form enum declarations. Chatwoot has 39 declarations in 31 files: 23 OSS and 8 Enterprise files.	Change enum status: ... to enum :status, ...; preserve prefixes, suffixes, defaults, scopes, and serialized values; run model/API specs.
ActiveSupport::ProxyObject	Jbuilder 2.11.5 uses the removed class.	Upgrade Jbuilder before the Rails 8 bump.
Active Record internal APIs	Rails removes deprecated connection-pool and schema behavior. Chatwoot subclasses a generic internal schema dumper constant.	Rework or remove the schema dumper monkey patch against the PostgreSQL dumper and verify triggers/indexes/schema output.
Active Job transaction setting	Old enqueue_after_transaction_commit configuration is deprecated on the path to removal in 8.1.	Use the supported boolean/per-job behavior and verify Sidekiq jobs around commit and rollback.
Azure Active Storage	The service is deprecated in 8.0.	Complete an extracted/custom adapter or customer migration before 8.1.
Fresh database migration behavior	db:migrate on a fresh database loads the schema before pending migrations.	Test both fresh schema load and upgrade from the oldest supported production schema.
New-app stack defaults	Propshaft, Solid Queue, Solid Cache, Solid Cable, Kamal, and the authentication generator are promoted for new apps.	Do not adopt them as part of the Rails upgrade. Existing Vite, Sprockets, Sidekiq, Redis, and Devise contracts should remain stable.

See the official Rails 8.0 release notes.

Rails 8.1 interface changes

Interface	Repo finding	Migration
Azure Active Storage service	Rails removes the built-in service. config/storage.yml still defines service: AzureStorage, selectable with ACTIVE_STORAGE_SERVICE=microsoft.	This is a hard production blocker for Azure-backed installations. Supply a maintained adapter with integration tests or formally migrate/deprecate Azure.
Routes	resource :app, only: [:index] fails Rails 8.1 route validation because a singular resource has no collection index action.	Express the route with an explicit scope/get while preserving every existing URL and helper consumed by the frontend.
Parameter parsing	Leading-bracket parameter names are no longer normalized and semicolons are no longer query separators.	Add request contract tests and sample production traffic for API, OAuth, and webhook query strings. Communicate any client-facing incompatibility.
Routes to multiple paths	Deprecated multi-path route support is removed.	Confirm all routes compile and compare rails routes before and after.
Time conversion	to_time now preserves the receiver timezone; Time/TimeWithZone arithmetic removals land.	Test the two application to_time call sites, especially reporting timezone boundaries and DST fixtures.
schema.rb order	Table columns are sorted alphabetically.	Expect a large one-file diff; isolate it in a schema-only commit and prove no semantic schema loss.
Active Job adapter	The Rails built-in Sidekiq adapter is deprecated in favor of the adapter shipped by Sidekiq. Symbol values and the application-level enqueue-after-commit setting are removed.	Update within Sidekiq 7.3.x, verify the loaded adapter origin, and test retries, schedules, unique/cron jobs, mail delivery, and transaction boundaries.
Custom job serializers	#klass must be public.	No custom serializer was found in the current tree; retain a boot-time registry check.
Redirect/JSON defaults	New 8.1 apps raise on path-relative redirects and stop escaping selected HTML characters in JSON.	When activating 8.1 defaults, audit 73 redirect_to call sites and API snapshots. Version-only boot can retain old behavior.
Order-dependent finders	Rails 8.1 deprecates order-dependent first calls without an order.	Capture deprecations in CI and fix only queries where nondeterminism matters.
ActiveSupport::Configurable	Deprecated in 8.1.	The experimental boot warning originates in omniauth-rails_csrf_protection 1.0.2; track or patch upstream before Rails 8.2.

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:

Removed/deprecated interface	Audit result
ActiveRecord::ConnectionAdapters::ConnectionPool#connection	No application or Enterprise call found.
Active Job :never, :always, and :default enqueue-after-commit values	No application configuration using these symbols found.
Application-level deprecated config.active_job.enqueue_after_transaction_commit	No current setting found; transaction/enqueue behavior still needs runtime tests.
Custom Active Job serializer private #klass	No custom Active Job serializer found.
SuckerPunch's internal Rails adapter	SuckerPunch is not the configured queue backend.
Time-to-TimeWithZone addition and Time#since(Time)	No direct application call pattern found; the two to_time call sites remain in scope.
SQLite adapter removals	Chatwoot's supported production path is PostgreSQL; fresh and upgraded PostgreSQL remain in the matrix.

Highest-risk break scenarios

Risk	Severity	What could break	Detection and containment
Encrypted credentials become unreadable	Critical	Email inbox passwords, social tokens, webhook secrets, OTP secrets, integration tokens, and Enterprise channel credentials.	Preflight decrypt scan with counts by model/attribute; dual-readable configuration; canary reads and writes; do not remove legacy support until all old processes and ciphertext are gone.
Azure file storage stops booting or serving files	Critical for affected installs	Upload, download, preview, direct upload, and purge operations when ACTIVE_STORAGE_SERVICE=microsoft.	Decide support policy before Rails 8.0; run Azure emulator/real-account contract tests; block Rails 8.1 rollout without a passing adapter.
Jobs run before commit or disappear on rollback	High	Notifications, email, webhooks, message fan-out, imports, search indexing, and reporting side effects.	Transaction integration specs plus Sidekiq smoke tests; compare enqueue and failure metrics during canary.
Authentication/session/signature invalidation	High	Agent sessions, API auth, OTP flows, signed IDs, password policy, OAuth, and Active Storage links.	Mixed-version rolling-deploy test; old cookie/token fixtures; fork compatibility specs; explicit serializer settings.
Super Admin loses CSS/JS or fields	High	Administrate 1 changes and loss of transitive Sprockets dependencies.	Make sprockets-rails explicit or migrate intentionally; production asset precompile; browser smoke every Super Admin CRUD path and custom field.
API or webhook parameter behavior changes	High	Leading-bracket or semicolon query strings from old/third-party clients.	Production log sampling, request fixtures, contract tests, and a documented client migration if such traffic exists.
Enum API/values drift	High	Scopes, predicates, validations, JSON values, database values, Enterprise policies, and background jobs.	Mechanical syntax-only commits split by domain; assert mappings before/after; run affected request/job specs.
Schema or fresh install drifts	High	Trigger definitions, schema loader, Active Storage duplicate migrations, and extension setup.	Compare schema objects, indexes, constraints, triggers, and extensions on upgraded and fresh PostgreSQL databases.
Time/reporting results shift	Medium	Daily boundaries, unread counts, report grouping, and DST behavior.	Timezone matrix tests for UTC, non-UTC, and DST transition dates.
Hidden Enterprise incompatibility	Medium to high	Overrides and prepended modules load after the OSS path appears healthy.	Run zeitwerk:check, the full Enterprise suite, and product smokes with Enterprise enabled at every checkpoint.

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.