Unleash client for Ruby
Switch branches/tags
Clone or download
Latest commit 2676d5a Nov 13, 2018



Build Status Coverage Status

Unleash client so you can roll out your features with confidence.

Leverage the Unleash Server for powerful feature toggling in your ruby/rails applications.


Add this line to your application's Gemfile:

gem 'unleash', '~> 0.1.4'

And then execute:

$ bundle

Or install it yourself as:

$ gem install unleash


It is required to configure the url of the unleash server. Please substitute the sample 'http://unleash.herokuapp.com/api' for the url of your own instance.

It is highly recommended to configure app_name and the instance_id.

For other options please see lib/unleash/configuration.rb.

Unleash.configure do |config|
  config.url      = 'http://unleash.herokuapp.com/api'
  config.app_name = 'my_ruby_app'

or instantiate the client with the valid configuration:

UNLEASH = Unleash::Client.new(url: 'http://unleash.herokuapp.com/api', app_name: 'my_ruby_app')

Usage in a plain Ruby Application

require 'unleash'
require 'unleash/context'

@unleash = Unleash::Client.new(url: 'http://unleash.herokuapp.com/api', app_name: 'my_ruby_app')

feature_name = "AwesomeFeature"
unleash_context = Unleash::Context.new
unleash_context.user_id = 123

if @unleash.is_enabled?(feature_name, unleash_context)
  puts " #{feature_name} is enabled according to unleash"
  puts " #{feature_name} is disabled according to unleash"

Usage in a Rails Application

Add Initializer

Put in config/initializers/unleash.rb:

Unleash.configure do |config|
  config.url      = 'http://unleash.herokuapp.com/api'
  config.app_name = Rails.application.class.parent.to_s
  # config.instance_id = "#{Socket.gethostname}"

UNLEASH = Unleash::Client.new

For config.instance_id use a string with a unique identification for the running instance. For example: it could be the hostname, if you only run one App per host. Or the docker container id, if you are running in docker. If it is not set the client will generate an unique UUID for each execution.

Add Initializer if using Puma

In puma.rb ensure that the unleash client is configured and instantiated as below, inside the on_worker_boot code block:

on_worker_boot do
  # ...

  Unleash.configure do |config|
    config.url      = 'http://unleash.herokuapp.com/api'
    config.app_name = Rails.application.class.parent.to_s
  Rails.configuration.unleash = Unleash::Client.new

Instead of the configuration in config/initializers/unleash.rb.

Set Unleash::Context

Be sure to add the following method and callback in the application controller to have @unleash_context set for all requests:

Add in app/controllers/application_controller.rb:

  before_action :set_unleash_context

  def set_unleash_context
    @unleash_context = Unleash::Context.new(
      session_id: session.id,
      remote_address: request.remote_ip,
      user_id: session[:user_id]

Or if you see better fit, only in the controllers that you will be using unleash.

Sample usage

Then wherever in your application that you need a feature toggle, you can use:

if UNLEASH.is_enabled? "AwesomeFeature", @unleash_context
  puts "AwesomeFeature is enabled"

or if client is set in Rails.configuration.unleash:

if Rails.configuration.unleash.is_enabled? "AwesomeFeature", @unleash_context
  puts "AwesomeFeature is enabled"

Local test client

bundle exec examples/simple.rb

Available Strategies

This client comes with the all the required strategies out of the box:

  • ApplicationHostnameStrategy
  • DefaultStrategy
  • GradualRolloutRandomStrategy
  • GradualRolloutSessionIdStrategy
  • GradualRolloutUserIdStrategy
  • RemoteAddressStrategy
  • UnknowndStrategy
  • UserWithIdStrategy


After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

See (TODO.md) for known limitations, and feature roadmap.


Bug reports and pull requests are welcome on GitHub at https://github.com/unleash/unleash-client-ruby.

Please include tests with any pull requests, to avoid regressions.