Put a stable control around a change.
A flag key stays in application code while its state changes in each environment. Start with a non-critical path, prove the off state, then promote the tested state deliberately.
- Create a flag such as
checkout_v2in a workspace. - Generate a separate SDK key for Development, Staging, or Production.
- Configure the Ruby client with a safe default and start background refresh.
- Guard the code path, test both branches, and change the audience from the dashboard.
It reads the complete environment configuration. Store it in the application secret mechanism, not browser code, source control, logs, or screenshots.
Choose the gate that matches the release.
A flag is on when any configured gate matches. Gate state is isolated by environment, so Development and Production can make different decisions for the same key.
| Gate | Use it for | Behavior |
|---|---|---|
| Boolean | All users | On for every evaluation in the selected environment. |
| Actor | Named accounts or tenants | On for listed stable actor identifiers. |
| Group | Application-defined cohorts | On when a registered predicate or explicit group matches. |
| % of actors | Gradual rollout | Deterministic per flag and actor; the cohort stays sticky as the percentage changes. |
| % of time | Sampling | Random per evaluation; not a sticky cohort. |
One initializer, one local check.
The gem uses Ruby's standard library, fetches configuration in the background, and exposes the same decision surface in Rails or a standalone Ruby process.
ToggleFleet.configure do |config| config.sdk_key = ENV.fetch("TOGGLEFLEET_SDK_KEY") config.default = false config.refresh_interval = 15 end ToggleFleet.start if ToggleFleet.enabled?(:checkout_v2, actor: current_user) render "checkout/v2" else render "checkout/current" end
The enabled? call reads the latest configuration held in memory. It does not block on a ToggleFleet request.
Refresh in the background. Keep deciding.
localHot path
After a configuration load, flag checks are in-process lookups rather than control-plane requests.
304Conditional refresh
The SDK sends an ETag on background polls. Unchanged configuration returns HTTP 304 with no JSON body to parse.
lastLast-good state
A failed refresh leaves the last loaded configuration in place. Unknown flags use the configured default before the first successful load.
actorStable targeting
Actor IDs feed deterministic percentage bucketing, so a rollout does not flicker for the same flag and actor.
Use the REST API when Ruby is not the caller.
Non-Ruby services can fetch an environment or evaluate one flag with an SDK key. Prefer /v1/config plus local evaluation for repeated checks; keep the credential on the server.
# Fetch and cache an environment curl https://togglefleet.com/v1/config \ -H "Authorization: Bearer $TOGGLEFLEET_SDK_KEY" \ -H 'If-None-Match: "…"' # Or evaluate one flag curl https://togglefleet.com/v1/evaluate \ -H "Authorization: Bearer $TOGGLEFLEET_SDK_KEY" \ -G --data-urlencode "flag=checkout_v2" \ --data-urlencode "actor=account_42"
The API intentionally does not expose environment configuration to browser JavaScript. Use the SDK or a server-side integration.
Questions before the first guarded branch.
Does a Ruby flag check call ToggleFleet over the network?
No. After configuration is loaded, ToggleFleet.enabled? reads in-process state. Background refresh uses conditional ETag requests separately.
Which feature-flag gates are available?
Boolean, actor, group, percentage of actors, and percentage of time. Gate state is independent for each environment.
What happens if ToggleFleet is unreachable?
The SDK keeps the last successfully loaded configuration. Before the first successful load, an unknown flag returns the configured safe default, which is false by default.
Are percentage-of-actors rollouts sticky?
Yes. The gate uses the flag and actor identifiers for deterministic bucketing. Percentage-of-time is random per evaluation and should not be used when stickiness matters.
Can another language use ToggleFleet?
Yes. Server-side clients can call /v1/config or /v1/evaluate with an environment SDK key. Keep the key out of browser bundles and prefer local evaluation for repeated checks.