Use Rails encrypted credentials for secrets that ship with the app, and keep the master key out of the repository. Use environment variables for values that differ per host or that your platform injects. Many teams combine both: credentials hold the bulk, and one variable, the master key, unlocks them.
How Rails credentials work
The Rails security guide explains that Rails stores secrets in config/credentials.yml.enc, which is encrypted and cannot be edited directly. Rails reads config/master.key, or 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.
You edit it with bin/rails credentials:edit, which creates the file and config/master.key if missing. Values are then read through Rails.application.credentials. By default the file contains secret_key_base, and it can hold API keys for external services.
Side by side
| Question | Encrypted credentials | Environment variables |
|---|---|---|
| Versioned with the code | Yes, encrypted | No |
| Change history in Git | Yes | Held by your platform |
| What must be protected | The master key | Each secret, in the platform |
| Per-environment values | Possible with separate files | Natural |
| Visible in process listings or dumps | Only after decryption | Can appear in env dumps |
| Rotation | Edit, commit, deploy | Update in platform, restart |
Choosing
Credentials fit when you want secrets reviewed with code changes, a single deployable artifact, and an audit trail of when a secret was edited. Environment variables fit when a platform already manages secrets with its own access controls, when values differ per deployment, or when a secret is shared across several apps.
The guide also suggests restricting access further using environment specific versions of these files. That means separate credentials for production and staging, with separate master keys, so a developer with staging access cannot decrypt production.
Steps to set it up well
- Put
config/master.keyin.gitignore. Rails generates it ignored, but check. - Provide the key to production through
RAILS_MASTER_KEYin your platform's secret store. - Use separate credentials per environment.
- Keep only secrets in credentials, not feature flags.
- Record who holds the master key and how to rotate it.
- Avoid printing credentials to logs. Rails also lets you filter parameters, which helps with request logs.
Common mistakes
- Committing
master.keynext to the encrypted file, which defeats the encryption. - Sharing one master key across every environment.
- Copying production credentials into a developer laptop to debug.
- Forgetting that the security guide warns the database config and other unencrypted secrets need protecting too.
Our post on rotating secret_key_base covers what changes when that particular secret moves.
Quick check
Can I commit credentials.yml.enc?
Yes. The Rails guide says the encrypted file can be stored in version control as long as the master key is kept safe.
Where should RAILS_MASTER_KEY live?
In your hosting platform's secret store or CI secrets, not in the repository or a shared chat.
Safeguard's compliance and evidence automation can help record how secrets are managed and rotated. A free scan is at gold.safeguard.sh/scan.
Sources
Last reviewed: 19 October 2026.
