Kreds: Streamlined Rails Credentials Access

Rails credentials are a convenient way to store secrets, but retrieving them could be more intuitive. Kreds provides a simpler, shorter, and safer way to access Rails credentials with blank value detection and 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:

• Getting Help and Contributing
• License
• Code of Conduct

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 path
• var - 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 exist
• Kreds::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 exist
• Kreds::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.