In a Rails app, secrets live in an encrypted file, config/credentials.yml.enc, and everything depends on the master key that decrypts it. Keep that key out of the repository, supply it through your deployment system, filter secrets from logs, and rotate secret_key_base knowing it signs out users.
How do Rails credentials work?
The Rails security guide says Rails stores secrets in config/credentials.yml.enc, which is encrypted and so cannot be edited directly. Rails uses config/master.key, or alternatively the RAILS_MASTER_KEY environment variable, to decrypt it. Because the file is encrypted, the guide says it can sit in version control as long as the master key is kept safe.
By default the file holds the application's secret_key_base. You can add other secrets such as access keys for external services.
The consequence is simple and often missed. The encrypted file is only as safe as the master key. If master.key is committed, or pasted into a ticket, the encryption protects nothing.
What does secret_key_base protect?
The guide says that in development and test, an app gets a secret_key_base derived from the app name, while other environments must use a random key present in the credentials file. The key feeds the signing and encryption of things like sessions and signed cookies.
Rotation has a cost. The guide notes that changing secret_key_base without rotating the old value will expire active sessions and require all users to log in again. If you suspect exposure, change it anyway, and announce the sign-out.
How do I keep secrets out of Rails logs?
The guide warns that encrypting secrets and passwords in the database is useless if the logs list them in clear text. Use config.filter_parameters to mark parameters as [FILTERED]. Rails adds default filters that include passw, secret and token, matched by partial regular expression, and the configuration guide says the filter also hides sensitive column values when you call inspect on an Active Record object.
Add any custom names you use, such as api_key or ssn, to that list. Then check a real log from a staging request.
What else does the guide tell you to protect?
It asks you to secure config/database.yml, the master key for credentials, and other unencrypted secrets, and suggests environment specific files to restrict access further.
How should the master key reach production?
Treat it the way the OWASP Secrets Management Cheat Sheet treats any long lived secret: limit who can read it, audit access, and be able to replace it. In practice that means the key lives in your deployment platform's secret store or a dedicated secrets manager, is injected as RAILS_MASTER_KEY at start, and is never baked into a container image layer, where anyone who can pull the image could read it.
Keep a short list of who holds a copy. Developers rarely need the production key at all. If your team edits production credentials from laptops, move that step into a reviewed pipeline, so changes have a trail.
Constructed example
A team stores a payment key in credentials.yml.enc and deploys with RAILS_MASTER_KEY set in the hosting platform. A developer later copies master.key into a shared chat to help a colleague. The team treats it as exposed: they generate new credentials, rotate the payment key at the provider, replace the master key in the platform, and cleanse the chat. Nothing in git changes except the new encrypted file.
What to do
- Confirm config/master.key is in the ignore file and has never been committed. Search the history.
- Supply RAILS_MASTER_KEY through your deployment platform, not a file in the image.
- Separate credentials per environment so a staging leak does not expose production.
- Extend config.filter_parameters with your own sensitive names.
- Plan a rotation procedure for secret_key_base and for each third party key, and rehearse the user sign-out.
- Add secret scanning to pull requests.
- Audit gems that touch secrets. Tools that read your Gemfile.lock can flag known vulnerable versions.
Quick check
Can I commit credentials.yml.enc?
Yes, according to the Rails guide, as long as the master key is kept safe and never committed.
What happens if I change secret_key_base?
Active sessions expire and users must log in again, unless you rotate the old value properly.
Sources
- Securing Rails Applications, Rails Guides
- Configuring Rails Applications, Rails Guides
- OWASP Secrets Management Cheat Sheet
Last reviewed: 18 October 2026.
