flippercloud/flipper: feature flags for Ruby that run without a network call

The problem flippercloud/flipper solves, and who it is for

Shipping a feature to every user at once is a one-way door. Flipper exists so a Ruby application can decide at runtime who sees what: everyone, a named actor, a group of actors, a percentage of actors, or a percentage of time. The README puts it plainly: "Flipper gives you control over who has access to features in your app."

The audience is narrow and specific. This is a Ruby library. The repository layout is dominated by gemspecs: flipper.gemspec, flipper-active_record.gemspec, flipper-redis.gemspec, flipper-mongo.gemspec, flipper-dalli.gemspec, flipper-moneta.gemspec, flipper-sequel.gemspec, flipper-api.gemspec, flipper-ui.gemspec, flipper-cloud.gemspec, flipper-rollout.gemspec. If you do not run Ruby, none of that helps you. If you do run Ruby, the split into separate gems is the point: you install the core and exactly one storage adapter, not a bundle of drivers you will never use.

The second audience is teams that already run Redis, Postgres, MySQL, MongoDB or Memcached and would rather not add another moving part to the request path. Flipper reads flags from a store you control. The README makes the consequence explicit for the hosted product: "All your feature flag reads are local to your app." The same property holds for the open source gem with a local adapter.

How Flipper evaluates a flag

The core API is a single predicate. The README's getting started example checks a flag with an actor:

if Flipper.enabled?(:search, current_user)
  puts 'Search away!'
else
  puts 'No search for you!'
end

Everything else is a way of writing the state that predicate reads. The README lists the enablement forms: Flipper.enable for everyone, Flipper.enable_actor for one actor, Flipper.enable_group for a group, and Flipper.enable_percentage_of_actors for a percentage. The repository's examples directory mirrors that vocabulary with files such as individual_actor.rb, group.rb, group_with_members.rb, group_dynamic_lookup.rb, percentage_of_actors.rb, percentage_of_actors_group.rb and percentage_of_time.rb. There is also an expressions.rb example, which suggests the library supports composed conditions beyond the flat forms in the README.

The default is the part that matters most in production. The README states: "All features are disabled by default, so you'll need to explicitly enable them." A flag you have never touched evaluates false. That is the safe direction, and it means a deploy that adds a new flag cannot accidentally turn the feature on for anyone.

Storage is abstracted behind adapters. The README points to an adapters page rather than enumerating them, but the gemspecs and the docker-compose.yml tell you what the project itself exercises: Redis, Mongo and Memcached services are defined there, with Postgres commented out. The app service in that compose file receives REDIS_URL, MONGODB_HOST and MEMCACHED_URL as environment variables, which is a fair hint about how each adapter is configured.

Groups deserve a closer look, because they are where Flipper stops being a simple on/off switch. A group is not a list of actors baked into the flag; examples/group_dynamic_lookup.rb and examples/group_with_members.rb suggest two different ways to answer the membership question, one resolving members at check time and one holding them explicitly. That distinction determines whether a group reflects your user table as it changes or a snapshot you have to keep in sync. The README does not spell out the trade-off, so read both example files before choosing.

The percentage forms are the other place where the mechanism matters. percentage_of_actors.rb and percentage_of_time.rb are separate examples because they answer different questions. Percentage of actors gives a stable cohort: the same user keeps seeing the same branch. Percentage of time is the opposite, a sampling switch that can flip between requests. If you want a gradual rollout that does not confuse a single user, the actor form is the one you want, and the README's own example passes 2 to mean two percent rather than a fraction.

Installing Flipper and gating your first feature

Add the core gem plus one adapter to your Gemfile. The README gives flipper-active_record as its example adapter, and the repository ships a matching gemspec, so that pairing is the documented path:

gem 'flipper'
gem 'flipper-active_record'

Then install with bundler, or install the core gem on its own if you are not using Bundler:

bundle
# or
gem install flipper

With an adapter loaded, enable a flag. The README's examples cover the four common scopes, and each one is a single call:

Flipper.enable :search
Flipper.enable_actor :search, current_user
Flipper.enable_group :search, :admin
Flipper.enable_percentage_of_actors :search, 2

After running those, Flipper.enabled?(:search, current_user) returns true for the actors you named and false for everyone else. Note the ordering in the percentage example: the README passes 2, which reads as two percent, not a fraction. Getting that wrong is the kind of mistake the API will not catch for you.

If you want a browser interface, flipper-ui.gemspec exists and the README mentions configuring flags "from the console or a web UI", but the README does not give the mount instructions here. Check the documentation site before wiring it into your routes. The same caution applies to flipper-api.gemspec: an HTTP surface for flags exists in the repository, and the README does not describe it, so treat the API as something to investigate in the documentation rather than something the README tells you to switch on.

Where Flipper is the wrong tool

The open source gem gives you the evaluation engine and the adapters. It does not give you a control plane. Multiple environments, personal environments, permissions, audit history and one-click rollback are listed in the README as features of Flipper Cloud, the commercial product, not of the gem. If your requirement is "a non-engineer toggles a flag in a dashboard and we can see who changed it last Tuesday", the gem alone does not satisfy that. You would be building the audit trail and the permissions layer yourself.

There is a second boundary. If your services are not written in Ruby, Flipper's adapters do not help you. The README mentions Cloud integrating with "Rails, Sinatra or any other framework", and the repository includes an examples/api directory and an flipper-api.gemspec, but the primary language is Ruby and the API surface is a Ruby DSL.

A third, quieter limitation: the README's own examples show flag state being set from application code (Flipper.enable :search inside your app). That is fine for a console session or a migration, but if flag state is written from request-handling code paths you have effectively hardcoded the rollout into your application. The library will not stop you from doing that.

Finally, consider the operational surface you are signing up for. Choosing flipper-redis means your flag state now lives in Redis alongside whatever else you keep there, and a flushed or evicted keyspace takes your rollout configuration with it. Choosing flipper-active_record means flag reads hit your primary database, which is fine at low volume and less fine when a flag is checked on every request of a hot path. The README asserts that Flipper can performantly store flags "regardless of what data store you are using", but it does not publish latency figures, so the performance question is one you answer against your own store rather than from the documentation.

Flipper compared with flipper-rollout

The most interesting comparison is inside this repository. flipper-rollout.gemspec and the examples/rollout directory exist to bridge Flipper with the older rollout gem. The difference in approach is where feature state lives. Rollout historically kept flags in Redis under its own key scheme and its own API. The Flipper adapter lets code that already speaks Flipper's API read and write flags that live in that rollout-shaped storage, so you can migrate incrementally rather than rewriting every call site at once.

That is a migration tool, not a reason to choose one over the other. If you are starting fresh, you pick Flipper and an adapter that matches your existing datastore. If you have a running rollout installation, the adapter is the path off it. The README does not document the adapter's behaviour in detail, so read examples/rollout before relying on it.

The broader comparison is against any hosted flag service. Those put a network call or a cached SDK between your code and the flag decision. Flipper with a local adapter puts the decision in your process, which is why the README can claim that Cloud's availability "won't affect yours". The trade is that you own the store, the backups and the migration path.

Maintenance, releases and the MIT licence

The repository is not archived and the last push was on 2026-09-16. The most recent release listed is v1.4.2 on 2026-05-11, following v1.4.1 on 2026-03-25 and v1.4.0 on 2026-02-26. That is a steady cadence rather than a burst, and the Changelog.md at the repository root is where the project records what changed between them.

Upgrade cost is low by construction. Because the adapters are separate gems, you can bump flipper without touching flipper-redis or flipper-active_record, and vice versa. The release process described in the README is a version bump in lib/flipper/version.rb, a tag, and GitHub Actions publishing all gems to RubyGems automatically, so the published artifacts track the repository tags.

The licence is MIT. That is permissive: it permits commercial use and modification with the licence notice retained. It is worth separating two things that share a name here. The MIT licence covers the gem. Flipper Cloud is a hosted service with its own free plan and its own terms, and the README links to a pricing page rather than describing the terms. Nothing in the MIT grant tells you anything about the service. If you plan to run both, treat them as two separate decisions.

Working on Flipper itself

If you are contributing rather than consuming, the README's contributing section gives the loop directly. Fork, branch, run the suite with bundle exec rake, commit, push, open a pull request:

git checkout -b my-new-feature
bundle exec rake
git commit -am 'Added some feature'
git push origin my-new-feature

The README points at docs/DockerCompose.md if you need all the adapters running locally, and docker-compose.yml defines redis, mongo and memcached services alongside an app container built from the repository Dockerfile. That Dockerfile is based on ruby:3.0 and sets BUNDLE_PATH to /bundle_cache. Postgres is present in the compose file but commented out, so a full adapter run needs that uncommented first. The README does not explain why Postgres is disabled by default, and the compose file's version key is "2.4", which is worth knowing if your local Docker tooling has moved past that schema.

Editorial conclusion

Adopt flippercloud/flipper if your application is Ruby or Rails and you want flag evaluation to happen locally against a store you already operate, with no external service in the read path. Do not adopt it if your stack is not Ruby, or if you need a hosted dashboard, per-environment inheritance and audit rollback without building them yourself. Before committing, verify which adapter matches your existing infrastructure, confirm that every flag starts disabled so your first deploy is safe, and check the licence and terms of the separate Flipper Cloud service if you intend to use it alongside the gem.

Frequently asked questions

Official sources

1. flippercloud/flipper on GitHub
2. License: MIT
3. Project website
4. README
5. Releases