DEV Community

Cover image for The Set-and-Forget Guide to Rails App Versioning
Zil Norvilis
Zil Norvilis

Posted on

The Set-and-Forget Guide to Rails App Versioning

#ruby #programming #oop #selfnote

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.

1. Installation

Add the gem to your Gemfile:

gem "rails_app_version"
Enter fullscreen mode Exit fullscreen mode

Then run the bundle command:

bundle install
Enter fullscreen mode Exit fullscreen mode

2. Initial Setup

The gem relies on a configuration file and a version source file. Run the generator to copy the default configuration:

rails app:version:config
Enter fullscreen mode Exit fullscreen mode

Next, create a VERSION file in your project root. This is where you will define your application's current version:

echo "1.0.0" > VERSION
Enter fullscreen mode Exit fullscreen mode

3. Verification

To verify the setup, start your Rails console. You should see a new "Welcome" banner displaying your Ruby version, environment, and application version:

$ 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

4. Basic Usage

Once installed, you can access the version information anywhere in your Rails application:

  • 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 %>

5. Features to Note

  • 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.

Integration with Release Please

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:

{
  "packages": {
    ".": {
      "release-type": "ruby",
      "package-name": "my-rails-app",
      "extra-files": ["VERSION"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

How it works in the pipeline:

  1. 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.
  2. Once you merge that PR, the new version is committed to main.
  3. 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.

Top comments (0)