Rails credentials are a convenient way to store secrets, but retrieving them could be more intuitive - that's where Kreds comes in. Kreds is a simpler, shorter, and safer way to access Rails credentials, with a few extra features built in. It provides environment variable fallback support and blank value detection with clear human-readable error messages.
Example of Usage:
Say you want to fetch [:recaptcha][:site_key]
from your Rails credentials but forgot to set a value or made a typo in the key name:
# Rails credentials (silent failure, unclear errors):
Rails.application.credentials[:recaptcha][:site_key]
# => nil
Rails.application.credentials[:captcha][:site_key]
# => undefined method `[]' for nil:NilClass (NoMethodError)
Rails.application.credentials.fetch(:recaptcha).fetch(:key)
# => key not found: :key (KeyError)
# Kreds (clear, human-readable errors):
Kreds.fetch!(:recaptcha, :site_key)
# => Blank value in credentials: [:recaptcha][:site_key] (Kreds::BlankCredentialsError)
Kreds.fetch!(:recaptcha, :key)
# => Credentials key not found: [:recaptcha][:key] (Kreds::UnknownCredentialsError)
Gem Usage:
- Installation
- Credential Fetching
- Environment-Scoped Credentials
- Environment Variables
- Debug and Inspection
Community Resources:
Add Kreds to your Gemfile:
gem "kreds"
Install the gem:
bundle install
Kreds.fetch!(*keys, var: nil, &block)
Fetches credentials from the Rails credentials store.
Parameters:
*keys
- Variable number of symbols representing the key pathvar
- Optional environment variable name as fallback&block
- Optional block to execute if fetch fails
Returns: The credential value
Raises:
Kreds::UnknownCredentialsError
- if the key path doesn't existKreds::BlankCredentialsError
- if the value exists but is blank
# Basic usage
Kreds.fetch!(:aws, :s3, :credentials, :access_key_id)
# With environment variable fallback
Kreds.fetch!(:aws, :access_key_id, var: "AWS_ACCESS_KEY_ID")
# With block
Kreds.fetch!(:api_key) do
raise MyCustomError, "API key not configured"
end
Kreds.env_fetch!(*keys, var: nil, &block)
Fetches credentials scoped by the current Rails environment (e.g., :production
, :staging
, :development
).
Parameters: Same as fetch!
Returns: The credential value from Rails.application.credentials[Rails.env]
followed by the provided key path
Raises: Same exceptions as fetch!
# Looks in credentials[:production][:recaptcha][:site_key] in production
Kreds.env_fetch!(:recaptcha, :site_key)
Kreds.var!(name, &block)
Fetches a value directly from environment variables.
Parameters:
name
- Environment variable name&block
- Optional block to execute if variable is missing/blank
Returns: The environment variable value
Raises:
Kreds::UnknownEnvironmentVariableError
- if the variable doesn't existKreds::BlankEnvironmentVariableError
- if the variable exists but is blank
# Direct environment variable access
Kreds.var!("AWS_ACCESS_KEY_ID")
# With block
Kreds.var!("THREADS") { 1 }
Kreds.show
Useful for debugging and exploring available credentials in the Rails console.
Returns: Hash containing all credentials
Kreds.show
# => { aws: { access_key_id: "...", secret_access_key: "..." }, ... }
Have a question or need assistance? Open a discussion in our discussions section for:
- Usage questions
- Implementation guidance
- Feature suggestions
Found a bug? Please create an issue with:
- A clear description of the problem
- Steps to reproduce the issue
- Your environment details (Rails version, Ruby version, etc.)
Ready to contribute? You can:
- Fix bugs by submitting pull requests
- Improve documentation
- Add new features (please discuss first in our discussions section)
Before contributing, please read the contributing guidelines
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the Kreds project is expected to follow the code of conduct.