Upgrading

Rehearse an AddAuth update with persisted sessions, pending mail and your customized pages before changing the deployed bundle.

This guide starts from the published 0.2.1 package. Read the target release’s changelog and availability first. The 0.x API can change between releases; a successful installation alone does not verify an upgrade.

Keep a recoverable starting point

1. Save the deployed Gemfile.lock, application revision, generated migrations and config/add_auth-ejections.json. Back up the database using your normal protected backup process.
2. Keep the same authentication keys, digest adapters, RP ID, origins, cookie configuration and account policy during the package update. Changing them is a separate migration that can invalidate sessions, proofs or encrypted jobs.
3. In a disposable host with synthetic accounts, establish an ordinary session, a revoked session, a passkey, a strict account, a pending email and a queued security notification. Retain one customized ejected page.
4. Record which web and worker revisions will run together. Do not assume arbitrary old/new workers are compatible because they use Active Job.

Update the application bundle

In the Rails host’s Gemfile, select the published target version you reviewed. Then run:

bundle update add_auth --conservative
bundle exec ruby -e 'require "add_auth"; puts AddAuth::VERSION'
bin/rails db:migrate:status

Run only the generators named by that release’s instructions, inspect the generated changes, and apply reviewed migrations with bin/rails db:migrate. Existing AddAuth generators preserve host files and do not apply migrations themselves. Repeat generation and migration in the rehearsal to check that they remain safe.

Review customized files

bin/rails add_auth:doctor

Doctor compares each stored upstream baseline with the new gem template. Its diff describes the upstream change; it is not a diff of your private customization. Review the change against your host file and incorporate applicable fixes while retaining your layout, copy and routing choices.

After testing one reviewed file, remove only that file’s entry from the files object in config/add_auth-ejections.json. Run the matching generator:

bin/rails generate add_auth:views

Use add_auth:controllers, add_auth:javascript or add_auth:mailer_views for those file types. The existing host file stays in place and the current upstream baseline is recorded. Review the manifest diff and run doctor again. Do not delete the entire manifest or use overwrite flags to silence an unreviewed warning.

Verify the persisted journeys

• Resume an existing ordinary session; verify that the revoked session remains denied.
• Sign in with the existing passkey. Check that the strict account still rejects password/email fallback and requires permitted proof for management.
• Deliver eligible pending mail through a worker running the new bundle. Confirm that GET remains inert, POST consumes the link once, and replay fails.
• Retry a pending notification and a duplicate completed delivery. Observe job outcomes without logging links, bearer cookies or ciphertext.
• Exercise the customized page, Turbo validation and permitted no-JavaScript navigation. Run doctor and the deployment checks.

Deploy and roll back deliberately

Apply additive migrations before switching readers and workers. If the release does not establish mixed-version job compatibility, pause new intake, drain or stop old workers, deploy the matching web/worker bundle and resume processing. Watch unavailable responses, failed jobs, pending-mail age and maintenance heartbeats.

The 0.2.1-to-0.2.2 package rehearsal preserves the existing schema, keys and job formats. Returning to the saved 0.2.1 bundle and its matching ejection manifest keeps spent proofs and revoked sessions denied in that scenario. That evidence does not authorize reversing future schema changes.

Keep current authentication records during code rollback. Restoring an old database snapshot can revive revoked sessions and spent proofs; it requires a separate incident recovery and revocation procedure. Do not return to the stock signed-ID session reader after adopting AddAuth bearer sessions. If the previous version cannot safely read new state, retain the compatible schema, stop affected entry points and deploy a correction.

Next, review the integration boundaries and symptom-based checks.