{"id":13427999,"url":"https://github.com/laserlemon/figaro","last_synced_at":"2025-04-23T20:48:40.909Z","repository":{"id":2902178,"uuid":"3910382","full_name":"laserlemon/figaro","owner":"laserlemon","description":"Simple Rails app configuration","archived":false,"fork":false,"pushed_at":"2024-04-28T11:47:34.000Z","size":346,"stargazers_count":3762,"open_issues_count":77,"forks_count":288,"subscribers_count":49,"default_branch":"main","last_synced_at":"2024-05-18T09:42:20.357Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/laserlemon.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["laserlemon"]}},"created_at":"2012-04-02T18:57:32.000Z","updated_at":"2024-06-18T11:07:30.956Z","dependencies_parsed_at":"2023-07-05T17:01:12.798Z","dependency_job_id":"c4064a73-8b36-4891-9cf1-c8a8b933fd5d","html_url":"https://github.com/laserlemon/figaro","commit_stats":{"total_commits":247,"total_committers":17,"mean_commits":"14.529411764705882","dds":0.08097165991902833,"last_synced_commit":"6ae998e8209a08f91a165822abecffc0a0626814"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laserlemon%2Ffigaro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laserlemon%2Ffigaro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laserlemon%2Ffigaro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laserlemon%2Ffigaro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/laserlemon","download_url":"https://codeload.github.com/laserlemon/figaro/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250513701,"owners_count":21443204,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T01:00:44.086Z","updated_at":"2025-04-23T20:48:40.882Z","avatar_url":"https://github.com/laserlemon.png","language":"Ruby","readme":"## 📢 UPDATE\n\nFigaro [v2](https://github.com/laserlemon/figaro/tree/v2) development is underway but _stalled_. I need your help! Please consider [sponsoring Figaro's development](https://github.com/sponsors/laserlemon).\n\nWith the constraints of a family and a full-time job, even the _emotional_ support that sponsorship provides is extremely valuable in re-energizing Figaro development. Thank you! 💛\n\n# ![Figaro](https://raw.githubusercontent.com/laserlemon/figaro/1f6e709/doc/title.png)\n\nSimple, Heroku-friendly Rails app configuration using `ENV` and a single YAML file\n\n[![Gem Version](https://img.shields.io/gem/v/figaro.svg)](http://badge.fury.io/rb/figaro)\n[![Build Status](https://img.shields.io/travis/laserlemon/figaro/master.svg)](https://travis-ci.org/laserlemon/figaro)\n\n**NOTE:** If you're using Figaro 0.7 or prior, please refer to the\n[appropriate documentation](https://github.com/laserlemon/figaro/tree/0-stable#readme)\nor [upgrade](#how-do-i-upgrade-to-figaro-10) to Figaro 1.0.\n\n## Why does Figaro exist?\n\nFigaro was written to make it easy to securely configure Rails applications.\n\nConfiguration values often include sensitive information. Figaro strives to be\nsecure by default by encouraging a convention that keeps configuration out of\nGit.\n\n## How does Figaro work?\n\nFigaro is inspired by the [Twelve-Factor App](http://12factor.net) methodology,\nwhich states:\n\n\u003e The twelve-factor app stores config in environment variables (often shortened to env vars or env). Env vars are easy to change between deploys without changing any code; unlike config files, there is little chance of them being checked into the code repo accidentally; and unlike custom config files, or other config mechanisms such as Java System Properties, they are a language- and OS-agnostic standard.\n\nThis is straightforward in production environments but local development\nenvironments are often shared between multiple applications, requiring multiple\nconfigurations.\n\nFigaro parses a Git-ignored YAML file in your application and loads its values\ninto `ENV`.\n\n### Getting Started\n\nAdd Figaro to your Gemfile and `bundle install`:\n\n```ruby\ngem \"figaro\"\n```\n\nFigaro installation is easy:\n\n\n```bash\n$ bundle exec figaro install\n```\n\nThis creates a commented `config/application.yml` file and adds it to your\n`.gitignore`. Add your own configuration to this file and you're done!\n\n### Example\n\nGiven the following configuration file:\n\n```yaml\n# config/application.yml\n\npusher_app_id: \"2954\"\npusher_key: \"7381a978f7dd7f9a1117\"\npusher_secret: \"abdc3b896a0ffb85d373\"\n```\n\nYou can configure [Pusher](http://pusher.com) in an initializer:\n\n```ruby\n# config/initializers/pusher.rb\n\nPusher.app_id = ENV[\"pusher_app_id\"]\nPusher.key    = ENV[\"pusher_key\"]\nPusher.secret = ENV[\"pusher_secret\"]\n```\n\n**Please note:** `ENV` is a simple key/value store. All values will be converted\nto strings. Deeply nested configuration structures are not possible.\n\n### Environment-Specific Configuration\n\nOftentimes, local configuration values change depending on Rails environment. In\nsuch cases, you can add environment-specific values to your configuration file:\n\n```yaml\n# config/application.yml\n\npusher_app_id: \"2954\"\npusher_key: \"7381a978f7dd7f9a1117\"\npusher_secret: \"abdc3b896a0ffb85d373\"\n\ntest:\n  pusher_app_id: \"5112\"\n  pusher_key: \"ad69caf9a44dcac1fb28\"\n  pusher_secret: \"83ca7aa160fedaf3b350\"\n```\n\nYou can also nullify configuration values for a specific environment:\n\n```yaml\n# config/application.yml\n\ngoogle_analytics_key: \"UA-35722661-5\"\n\ntest:\n  google_analytics_key: ~\n```\n\n### Using `Figaro.env`\n\n`Figaro.env` is a convenience that acts as a proxy to `ENV`.\n\nIn testing, it is sometimes more convenient to stub and unstub `Figaro.env` than\nto set and reset `ENV`. Whether your application uses `ENV` or `Figaro.env` is\nentirely a matter of personal preference.\n\n```yaml\n# config/application.yml\n\nstripe_api_key: \"sk_live_dSqzdUq80sw9GWmuoI0qJ9rL\"\n```\n\n```ruby\nENV[\"stripe_api_key\"] # =\u003e \"sk_live_dSqzdUq80sw9GWmuoI0qJ9rL\"\nENV.key?(\"stripe_api_key\") # =\u003e true\nENV[\"google_analytics_key\"] # =\u003e nil\nENV.key?(\"google_analytics_key\") # =\u003e false\n\nFigaro.env.stripe_api_key # =\u003e \"sk_live_dSqzdUq80sw9GWmuoI0qJ9rL\"\nFigaro.env.stripe_api_key? # =\u003e true\nFigaro.env.google_analytics_key # =\u003e nil\nFigaro.env.google_analytics_key? # =\u003e false\n```\n\n### Required Keys\n\nIf a particular configuration value is required but not set, it's appropriate to\nraise an error. With Figaro, you can either raise these errors proactively or\nlazily.\n\nTo proactively require configuration keys:\n\n```ruby\n# config/initializers/figaro.rb\n\nFigaro.require_keys(\"pusher_app_id\", \"pusher_key\", \"pusher_secret\")\n```\n\nIf any of the configuration keys above are not set, your application will raise\nan error during initialization. This method is preferred because it prevents\nruntime errors in a production application due to improper configuration.\n\nTo require configuration keys lazily, reference the variables via \"bang\" methods\non `Figaro.env`:\n\n```ruby\n# config/initializers/pusher.rb\n\nPusher.app_id = Figaro.env.pusher_app_id!\nPusher.key    = Figaro.env.pusher_key!\nPusher.secret = Figaro.env.pusher_secret!\n```\n\n### Deployment\n\nFigaro is written with deployment in mind. In fact, [Heroku](https://www.heroku.com)'s\nuse of `ENV` for application configuration was the original inspiration for\nFigaro.\n\n#### Heroku\n\nHeroku already makes setting application configuration easy:\n\n```bash\n$ heroku config:set google_analytics_key=UA-35722661-5\n```\n\nUsing the `figaro` command, you can set values from your configuration file all\nat once:\n\n```bash\n$ figaro heroku:set -e production\n```\n\nFor more information:\n\n```bash\n$ figaro help heroku:set\n```\n\n#### Other Hosts\n\nIf you're not deploying to Heroku, you have two options:\n\n* Generate a remote configuration file\n* Set `ENV` variables directly\n\nGenerating a remote configuration file is preferred because of:\n\n* familiarity – Management of `config/application.yml` is like that of `config/database.yml`.\n* isolation – Multiple applications on the same server will not produce configuration key collisions.\n\n## Is Figaro like [dotenv](https://github.com/bkeepers/dotenv)?\n\nYes. Kind of.\n\nFigaro and dotenv were written around the same time to solve similar problems.\n\n### Similarities\n\n* Both libraries are useful for Ruby application configuration.\n* Both are popular and well maintained.\n* Both are inspired by Twelve-Factor App's concept of proper [configuration](http://12factor.net/config).\n* Both store configuration values in `ENV`.\n\n### Differences\n\n* Configuration File\n  * Figaro expects a single file.\n  * Dotenv supports separate files for each environment.\n* Configuration File Format\n  * Figaro expects YAML containing key/value pairs.\n  * Dotenv convention is a collection of `KEY=VALUE` pairs.\n* Security vs. Convenience\n  * Figaro convention is to never commit configuration files.\n  * Dotenv encourages committing configuration files containing development values.\n* Framework Focus\n  * Figaro was written with a focus on Rails development and conventions.\n  * Dotenv was written to accommodate any type of Ruby application.\n\nEither library may suit your configuration needs. It often boils down to\npersonal preference.\n\n## Is application.yml like [secrets.yml](https://github.com/rails/rails/blob/v4.1.0/railties/lib/rails/generators/rails/app/templates/config/secrets.yml)?\n\nYes. Kind of.\n\nRails 4.1 introduced the `secrets.yml` convention for Rails application\nconfiguration. Figaro predated the Rails 4.1 release by two years.\n\n### Similarities\n\n* Both are useful for Rails application configuration.\n* Both are popular and well maintained.\n* Both expect a single YAML file.\n\n### Differences\n\n* Configuration Access\n  * Figaro stores configuration values in `ENV`.\n  * Rails stores configuration values in `Rails.application.secrets`.\n* Configuration File Structure\n  * Figaro expects YAML containing key/value string pairs.\n  * Secrets may contain nested structures with rich objects.\n* Security vs. Convenience\n  * Figaro convention is to never commit configuration files.\n  * Secrets are committed by default.\n* Consistency\n  * Figaro uses `ENV` for configuration in every environment.\n  * Secrets encourage using `ENV` for production only.\n* Approach\n  * Figaro is inspired by Twelve-Factor App's concept of proper [configuration](http://12factor.net/config).\n  * Secrets are… not.\n\nThe emergence of a configuration convention for Rails is an important step, but\nas long as the last three differences above exist, Figaro will continue to be\ndeveloped as a more secure, more consistent, and more standards-compliant\nalternative to `secrets.yml`.\n\nFor more information, read the original [The Marriage of Figaro… and Rails](http://www.collectiveidea.com/blog/archives/2013/12/18/the-marriage-of-figaro-and-rails/) blog post.\n\n## How do I upgrade to Figaro 1.0?\n\nIn most cases, upgrading from Figaro 0.7 to 1.0 is painless. The format\nexpectations for `application.yml` are the same in 1.0 and values from\n`application.yml` are loaded into `ENV` as they were in 0.7.\n\nHowever, there are breaking changes:\n\n### `Figaro.env`\n\nIn Figaro 0.7, calling a method on the `Figaro.env` proxy would raise an error\nif a corresponding key were not set in `ENV`.\n\nIn Figaro 1.0, calling a method on `Figaro.env` corresponding to an unset key\nwill return `nil`. To emulate the behavior of Figaro 0.7, use \"bang\" methods as\ndescribed in the [Required Keys](#required-keys) section.\n\n**NOTE:** In Figaro 0.7, `Figaro.env` inherited from `Hash` but in Figaro 1.0,\nhash access has been removed.\n\n### Heroku Configuration\n\nIn Figaro 0.7, a Rake task existed to set remote Heroku configuration according\nto values in `application.yml`.\n\nIn Figaro 1.0, the Rake task was replaced by a command for the `figaro`\nexecutable:\n\n```bash\n$ figaro heroku:set -e production\n```\n\nFor more information:\n\n```bash\n$ figaro help heroku:set\n```\n\n**NOTE:** The environment option is required for the `heroku:set` command. The\nRake task in Figaro 0.7 used the default of \"development\" if unspecified.\n\n### Spring Configuration\n\nIf you're using Spring, either [stop](http://collectiveidea.com/blog/archives/2015/02/04/spring-is-dead-to-me)\nor add `config/application.yml` to the watch list:\n\n```rb\n# config/spring.rb\n\n%w(\n  ...\n  config/application.yml\n).each { |path| Spring.watch(path) }\n```\n\n## Who wrote Figaro?\n\nMy name is Steve Richert and I wrote Figaro in March, 2012 with overwhelming\nencouragement from my employer, [Collective Idea](http://www.collectiveidea.com).\nFigaro has improved very much since then, thanks entirely to [inspiration](https://github.com/laserlemon/figaro/issues)\nand [contribution](https://github.com/laserlemon/figaro/graphs/contributors)\nfrom developers everywhere.\n\n**Thank you!**\n\n## How can I help?\n\nFigaro is open source and contributions from the community are encouraged! No\ncontribution is too small.\n\nSee Figaro's [contribution guidelines](CONTRIBUTING.md) for more information.\n","funding_links":["https://github.com/sponsors/laserlemon"],"categories":["Environment Variables","Configuration","Ruby","环境变量","Gems"],"sub_categories":["Omniauth","Configuration and environment variables"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaserlemon%2Ffigaro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flaserlemon%2Ffigaro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaserlemon%2Ffigaro/lists"}