Tools: The Set-and-Forget Guide to Rails App Versioning

1. Installation ## 2. Initial Setup ## 3. Verification ## 4. Basic Usage ## 5. Features to Note ## Integration with Release Please The rails_app_version gem is a lightweight tool designed to manage and expose your application's version and environment information. This is particularly useful for debugging, cache-busting, and error tracking. Here is a brief guide to getting it set up in your Rails project. Add the gem to your Gemfile: Then run the bundle command: The gem relies on a configuration file and a version source file. Run the generator to copy the default configuration: Next, create a VERSION file in your project root. This is where you will define your application's current version: To verify the setup, start your Rails console. You should see a new "Welcome" banner displaying your Ruby version, environment, and application version: Once installed, you can access the version information anywhere in your Rails application: In Views (for cache busting): To make rails_app_version work seamlessly with an automated release workflow like Release Please, you can sync them through the root VERSION file. This allows Release Please to handle the semantic versioning and changelog, while rails_app_version handles the actual exposure of that version in your Rails app. To link the two, configure Release Please to treat your VERSION file as the source of truth. In your .github/workflows/release-please.yml or release-please-config.json, use the extra-files feature or a generic release type to ensure it bumps the version in that specific file: How it works in the pipeline: Templates let you quickly answer FAQs or store snippets for re-use. Are you sure you want to hide this comment? It will become hidden in your post, but will still be visible via the comment's permalink. Hide child comments as well For further actions, you may consider blocking this person and/or reporting abuse CODE_BLOCK: gem "rails_app_version" Enter fullscreen mode Exit fullscreen mode CODE_BLOCK: gem "rails_app_version" CODE_BLOCK: gem "rails_app_version" CODE_BLOCK: bundle install Enter fullscreen mode Exit fullscreen mode CODE_BLOCK: bundle install CODE_BLOCK: bundle install CODE_BLOCK: rails app:version:config Enter fullscreen mode Exit fullscreen mode CODE_BLOCK: rails app:version:config CODE_BLOCK: rails app:version:config COMMAND_BLOCK: echo "1.0.0" > VERSION Enter fullscreen mode Exit fullscreen mode COMMAND_BLOCK: echo "1.0.0" > VERSION COMMAND_BLOCK: echo "1.0.0" > VERSION COMMAND_BLOCK: $ rails c Welcome to the Rails console! Ruby version: 3.2.0 Application environment: development Application version: 1.0.0 Enter fullscreen mode Exit fullscreen mode COMMAND_BLOCK: $ rails c Welcome to the Rails console! Ruby version: 3.2.0 Application environment: development Application version: 1.0.0 COMMAND_BLOCK: $ rails c Welcome to the Rails console! Ruby version: 3.2.0 Application environment: development Application version: 1.0.0 COMMAND_BLOCK: Rails.application.version # => "1.0.0" Rails.application.env # => "development" COMMAND_BLOCK: Rails.application.version # => "1.0.0" Rails.application.env # => "development" CODE_BLOCK: <%= stylesheet_link_tag "application", "data-turbo-track": "reload", v: Rails.application.version %> CODE_BLOCK: <%= stylesheet_link_tag "application", "data-turbo-track": "reload", v: Rails.application.version %> CODE_BLOCK: { "packages": { ".": { "release-type": "ruby", "package-name": "my-rails-app", "extra-files": ["VERSION"] } } } Enter fullscreen mode Exit fullscreen mode CODE_BLOCK: { "packages": { ".": { "release-type": "ruby", "package-name": "my-rails-app", "extra-files": ["VERSION"] } } } CODE_BLOCK: { "packages": { ".": { "release-type": "ruby", "package-name": "my-rails-app", "extra-files": ["VERSION"] } } } - In Ruby code: Rails.application.version # => "1.0.0" Rails.application.env # => "development" - In Views (for cache busting): <%= stylesheet_link_tag "application", "data-turbo-track": "reload", v: Rails.application.version %> - Automatic Headers: The gem automatically injects X-App-Version and X-App-Environment headers into every HTTP response. This allows you to verify which version is running simply by inspecting the network headers in your browser. - Git Integration: If your project is a Git repository, the gem can optionally include the current Git revision (SHA) in the version string. - Cache Keys: You can use Rails.application.version.to_cache_key to generate unique keys for Rails.cache, ensuring that new deployments automatically invalidate old cached data. - Release Please monitors your commits. When you merge a feature or fix (using Conventional Commits), it opens a "Release PR" that automatically increments the number inside your VERSION file. - Once you merge that PR, the new version is committed to main. - rails_app_version reads the updated VERSION file during boot in your production environment, instantly reflecting the new version in your app's headers (X-App-Version), cache keys, and console banner without any manual intervention.