Understanding Rails secrets/credentials

Credentials are stored in config/credentials.yml.enc

At the risk of stating the obvious, your secrets are stored in config/credentials.yml.enc . That file is encrypted.

There of course needs to be a way to securely decrypt this encrypted file. That’s done using something called a master key . The master key is just a hash string that gets stored in one of two places: a file called config/master.key (which should NOT be committed to version control) or a RAILS_MASTER_KEY environment variable.

The development master key and production master key are the same

A key thing to understand, which I found counterintuitive, is that the master key you use in production should be the same as the master key you use in development . If your development master key is stored in config/master.key , create an identical config/master.key on production, containing the same exact key. If your development master key is stored in the RAILS_MASTER_KEY environment variable, set the production RAILS_MASTER_KEY to the exact same value.

I found this counterintuitive because usually I try to make all my passwords, etc. different for each environment I have. I thought I would need to create a different master key for my production environment. No, I need to not create a different master key.

The credentials.yml.enc file is edited in a special way

Since it’s encrypted, the config/credentials.yml.enc file can’t be edited directly. It can only be edited using the rails credentials:edit command.

What often throws me for a loop is that a prerequisite to using rails credentials:edit is having the EDITOR environment variable set, which on a fresh production machine I usually don’t. I’m aVim guy, so I run export EDITOR=vim and then I’m good to go. Then I can run rails credentials:edit and the command will open the credential file, decrypted, in Vim.

secrets.yml is obsolete

If you find something online that refers to secrets.yml , you’re looking at an old post. Before Rails 5.2 , there was a secrets.yml and secrets.yml.enc instead of the new credentials-related files. Don’t make the mistake of conflating Rails secrets with Rails credentials (like I did several times before learning better!).

The steps for setting up credentials in production

1. Take the same master key you’re using in development and put it either in config/master.key or the RAILS_MASTER_KEY environment variable.
2. Set the EDITOR environment variable to your favorite terminal-based editor.
3. Run rails credentials:edit to verify that your master key is working properly.

Helpful links

I hope my credentials guide is the new best guide on the internet but I’ll link to the sources that helped me put this together.

• Securing Rails Applications (official Rails guide)
• Rails 5.2. release notes
• DHH’s credentials pull request
• Stefan Wintermeyer’s credentials post

Best of luck with your credential management endeavors.

•  
•  
•  
• 2