Project

state_sync

0.0
The project is in a healthy, maintained state
state_syncspmarisa/state_syncHomepageDocumentationSource CodeBug TrackerWiki
Fetch and auto-refresh YAML-based feature flags and config from a Git repository.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Popularity
Downloads
188
Stars
0
Forks
0
Watchers
0
 Releases
Current version
0.1.0
Total releases
1
First release
2026-04-01
Latest release
2026-04-01
 Development
Primary Language
Ruby
Licenses
WTFPL
Average date of last 50 commits
2026-03-31
Reverse Dependencies
0

 Dependencies

Development

rspec
~> 3.13
webmock
~> 3.23
 Project Readme

state_sync

A Ruby gem for fetching YAML-based feature flags and configuration from a GitHub or GitLab repository. Values are loaded at startup and can optionally be kept fresh in the background.

Installation

Add to your Gemfile:

gem "state_sync"

Or install directly:

gem install state_sync

Configuration

Token setup: GITHUB.md | GITLAB.md

# config/initializers/state_sync.rb
StateSync.configure do |config|
  config.provider              = :github          # :github or :gitlab
  config.repo                  = "your-org/your-repo"  # "owner/repo" on GitHub or GitLab
  config.token                 = ENV["GITHUB_TOKEN"]   # optional for public repos
  config.auto_refresh          = false            # true or false (default: false)
  config.auto_refresh_interval = 300              # seconds, only required when auto_refresh is true
end

Usage

# Load a YAML file — fetches immediately on this line
CUSTOMERS = StateSync.load("config/customers.yml")

# Access data
CUSTOMERS.data              # => {"customer_ids" => [1001, 1002, 1003], "feature_x" => true}
CUSTOMERS["customer_ids"]   # => [1001, 1002, 1003]
CUSTOMERS["feature_x"]      # => true

# Force a manual refresh at any time
CUSTOMERS.reload!

Example YAML file

customer_ids:
  - 1001
  - 1002
  - 1003

feature_x: true

Loading multiple files

You can load as many files as you need — each gets its own store with independent data and refresh cycle. Define them in your initializer and use them anywhere in your app:

# config/initializers/state_sync.rb
StateSync.configure do |config|
  config.provider = :github
  config.repo     = "your-org/your-repo"  # "owner/repo" on GitHub or GitLab
  config.token    = ENV["GITHUB_TOKEN"]
end

CUSTOMERS       = StateSync.load("config/customers.yml")
FEATURE_FLAGS   = StateSync.load("config/feature_flags.yml")
PAYMENT_METHODS = StateSync.load("config/payment_methods.yml")
PAYMENT_LIMITS  = StateSync.load("config/payment_limits.yml")
# Use anywhere in your app
CUSTOMERS["customer_ids"]
FEATURE_FLAGS["new_checkout_flow"]
PAYMENT_METHODS["enabled"]
PAYMENT_LIMITS["daily_limit"]

Error handling

begin
  flags = StateSync.load("config/flags.yml")
rescue StateSync::ConfigurationError => e
  # Missing or invalid configuration
rescue StateSync::FetchError => e
  # Network error, bad token, file not found, etc.
end

Try it in IRB

First install the gem:

gem install state_sync

Then start IRB and require the gem:

irb
require "state_sync"

StateSync.configure do |config|
  config.provider = :github
  config.repo     = "spmarisa/state_sync_data"  # public repo, no token needed
end

customers = StateSync.load("allowed_customers.yml")
customers.data
customers["customer_ids"]

# Force a refresh
customers.reload!