Use Rails.app.creds for combined ENV + credentials lookup

Backport Rails 8.2's unified credentials API (Rails.app.creds) that
checks ENV first, then falls back to encrypted credentials. This makes
.env and rails credentials interchangeable - developers can choose
either approach without code changes.

- Add config/initializers/app_credentials.rb polyfill (remove after Rails 8.2 upgrade)
- Replace all Rails.application.credentials.dig calls with Rails.app.creds.option
- Update .env.example to mirror all credential keys using double-underscore convention
- Update Gemfile to Rails ~> 8.1.2

https://claude.ai/code/session_018vkGAjms65YpjwUidRYLkL

Author: claude

.env.example

@@ -1,6 +1,57 @@
-# Solid Queue Configuration
+# =============================================================================
+# Environment Variables
+# =============================================================================
+# Copy this file to .env and fill in the values.
+# These ENV vars are interchangeable with Rails encrypted credentials.
+# Rails.app.creds checks ENV first, then falls back to encrypted credentials.
+# Nested credential keys use "__" (double underscore) as separator.
+#
+# For example, credentials.dig(:stripe, :private_key) maps to STRIPE__PRIVATE_KEY
+# =============================================================================
+
+# --- Stripe Payments ---
+STRIPE__PRIVATE_KEY=sk_test_
+STRIPE__PUBLIC_KEY=pk_test_
+STRIPE__WEBHOOK_RECEIVE_TEST_EVENTS=true
+STRIPE__SIGNING_SECRET=whsec_
+
+# --- OAuth: Google ---
+GOOGLE_OAUTH2__CLIENT_ID=
+GOOGLE_OAUTH2__CLIENT_SECRET=
+
+# --- OAuth: GitHub ---
+GITHUB__KEY=
+GITHUB__SECRET=
+
+# --- Telegram ---
+TELEGRAM__BOT_NICKNAME=
+TELEGRAM__BOT_SECRET=
+
+# --- SMTP ---
+SMTP__USER_NAME=
+SMTP__PASSWORD=
+
+# --- S3 Storage ---
+S3__ACCESS_KEY_ID=
+S3__SECRET_ACCESS_KEY=
+S3__REGION=
+S3__BUCKET=
+
+# --- Active Record Encryption ---
+ACTIVE_RECORD_ENCRYPTION__PRIMARY_KEY=
+ACTIVE_RECORD_ENCRYPTION__DETERMINISTIC_KEY=
+ACTIVE_RECORD_ENCRYPTION__KEY_DERIVATION_SALT=
+
+# --- Tigris S3-compatible Storage (used via direct ENV) ---
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_ACCESS_KEY=
+AWS_ENDPOINT_URL_S3=
+BUCKET_NAME=
+
+# --- Application ---
 SOLID_QUEUE_IN_PUMA=true
+HOST=localhost:3000
 
-# Avo License Key (if using Avo Pro)
-AVO_LICENSE_KEY=''
-OPENAI_API_KEY=''
+# --- Third-party ---
+AVO_LICENSE_KEY=
+OPENAI_API_KEY=

Gemfile

@@ -5,7 +5,7 @@ source "https://rubygems.org"
 ruby file: ".ruby-version"
 
 # Bundle edge Rails instead: gem "rails", github: "rails/rails", branch: "main"
-gem "rails", "~> 8.1.1"
+gem "rails", "~> 8.1.2"
 # The modern asset pipeline for Rails [https://github.com/rails/propshaft]
 gem "propshaft"
 # Use postgresql as the database for Active Record

app/controllers/organizations/subscriptions_controller.rb

@@ -57,6 +57,6 @@ def sync_subscriptions
   end
 
   def require_billing_enabled
-    redirect_to organization_url(@organization) if Rails.application.credentials.dig(:stripe, :private_key).blank?
+    redirect_to organization_url(@organization) if Rails.app.creds.option(:stripe, :private_key).blank?
   end
 end

app/models/connected_account.rb

@@ -6,7 +6,7 @@ class ConnectedAccount < ApplicationRecord
   validates :provider, presence: true
   validates :uid, presence: true, uniqueness: { scope: :provider }
 
-  encrypts :access_token, :refresh_token if Rails.application.credentials.active_record_encryption.present?
+  encrypts :access_token, :refresh_token if Rails.app.creds.option(:active_record_encryption, :primary_key).present?
 
   PROVIDER_CONFIG = {
     google_oauth2: {

app/models/stripe_price.rb

@@ -84,7 +84,7 @@ def configured_price_ids
     end
 
     def stripe_configured?
-      Rails.application.credentials.dig(:stripe, :private_key).present?
+      Rails.app.creds.option(:stripe, :private_key).present?
     end
   end
 end

app/views/shared/_navbar.html.erb

@@ -24,7 +24,7 @@
 
           <% if Current.membership.admin? %>
             <%= nav_link t("organizations.edit.title"), edit_organization_path(Current.organization), icon: "svg/cog-6-tooth.svg", active: [["organizations"], ["edit"]] %>
-            <%= nav_link t("organizations.subscriptions.index.title"), organization_subscriptions_path(Current.organization), icon: subscription_status_label(Current.organization) if Rails.application.credentials.dig(:stripe, :private_key).present? %>
+            <%= nav_link t("organizations.subscriptions.index.title"), organization_subscriptions_path(Current.organization), icon: subscription_status_label(Current.organization) if Rails.app.creds.option(:stripe, :private_key).present? %>
           <% end %>
         </ul>
       </div>

app/views/shared/_sidebar.html.erb

@@ -25,7 +25,7 @@
 
                 <% if Current.membership.admin? %>
                   <%= nav_link t("organizations.edit.title"), edit_organization_path(Current.organization), icon: "svg/cog-6-tooth.svg", active: [["organizations"], ["edit"]] %>
-                  <%= nav_link t("organizations.subscriptions.index.title"), organization_subscriptions_path(Current.organization), icon: subscription_status_label(Current.organization) if Rails.application.credentials.dig(:stripe, :private_key).present? %>
+                  <%= nav_link t("organizations.subscriptions.index.title"), organization_subscriptions_path(Current.organization), icon: subscription_status_label(Current.organization) if Rails.app.creds.option(:stripe, :private_key).present? %>
                 <% end %>
               </ul>
             </details>

app/views/shared/_sidebar_links.html.erb

@@ -2,6 +2,6 @@
 
 <%= nav_link t("organizations.dashboard.index.title"), organization_dashboard_path(Current.organization), icon: "svg/chart-bar.svg" %>
 
-<%= nav_link t("organizations.dashboard.paywalled_page.title"), organization_paywalled_page_path(Current.organization), icon: "🔐" if Rails.application.credentials.dig(:stripe, :private_key).present? %>
+<%= nav_link t("organizations.dashboard.paywalled_page.title"), organization_paywalled_page_path(Current.organization), icon: "🔐" if Rails.app.creds.option(:stripe, :private_key).present? %>
 
 <%= nav_link "Projects", organization_projects_path(Current.organization), icon: "svg/question-mark-circle.svg" if policy(Project).index? %>

config/environments/production.rb

@@ -59,10 +59,10 @@
   # Set host to be used by links generated in mailer templates.
   config.action_mailer.default_url_options = { host: ENV.fetch("HOST", "example.com") }
 
-  # Specify outgoing SMTP server. Remember to add smtp/* credentials via bin/rails credentials:edit.
+  # Specify outgoing SMTP server. Set via credentials or ENV (SMTP__USER_NAME, SMTP__PASSWORD).
   # config.action_mailer.smtp_settings = {
-  #   user_name: Rails.application.credentials.dig(:smtp, :user_name),
-  #   password: Rails.application.credentials.dig(:smtp, :password),
+  #   user_name: Rails.app.creds.option(:smtp, :user_name),
+  #   password: Rails.app.creds.option(:smtp, :password),
   #   address: "smtp.example.com",
   #   port: 587,
   #   authentication: :plain
@@ -95,8 +95,8 @@
   # config.action_mailer.smtp_settings = {
   #   port: 587,
   #   address: "email-smtp.eu-central-1.amazonaws.com",
-  #   user_name: Rails.application.credentials.dig(:smtp, :user_name),
-  #   password: Rails.application.credentials.dig(:smtp, :password),
+  #   user_name: Rails.app.creds.option(:smtp, :user_name),
+  #   password: Rails.app.creds.option(:smtp, :password),
   #   authentication: :plain,
   #   enable_starttls_auto: true
   # }

config/initializers/app_credentials.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Backport of Rails 8.2 combined credentials (Rails.app.creds).
+# Checks ENV first, then falls back to encrypted credentials.
+# ENV keys are derived by uppercasing and joining nested keys with "__" (double underscore).
+#
+# Examples:
+#   Rails.app.creds.option(:stripe, :private_key)
+#   # => ENV["STRIPE__PRIVATE_KEY"] || credentials.dig(:stripe, :private_key)
+#
+#   Rails.app.creds.require(:stripe, :private_key)
+#   # => same, but raises KeyError if missing from both
+#
+# TODO: Remove this file after upgrading to Rails 8.2+
+
+unless Rails.respond_to?(:app)
+  class AppCreds
+    def option(*keys, default: nil)
+      env_value(*keys) || Rails.application.credentials.dig(*keys) || default
+    end
+
+    def require(*keys)
+      value = option(*keys)
+      raise KeyError, "Missing credential: #{keys.map(&:to_s).join('.')}" if value.blank?
+      value
+    end
+
+    private
+
+    def env_value(*keys)
+      env_key = keys.map { |k| k.to_s.upcase }.join("__")
+      ENV[env_key].presence
+    end
+  end
+
+  class AppContainer
+    def creds
+      @creds ||= AppCreds.new
+    end
+
+    def credentials
+      Rails.application.credentials
+    end
+  end
+
+  Rails.define_singleton_method(:app) { @_app ||= AppContainer.new }
+end