What this feature is for

The credentials feature is a way of storing secrets that you don’t want to keep in plaintext, like AWS credentials for example. (In fact, the one and only thing I keep in my main Rails project’s credentials are my Active Storage AWS credentials.)

Why the credentials feature is difficult to learn about

I personally have found Rails credentials really hard to understand. I think there are three reasons why this is.

1. The official Rails docs about the credentials feature are a little terse and not easily discoverable.
2. The feature changed somewhat drastically from Rails 4 to Rails 5, even changing names from “secrets” to “credentials”.
3. I only need to use the feature once in a while, when I’m deploying an application for the first time, meaning there’s lots of time in between to forget everything I knew.

How to work with credentials without frustration

There are perhaps five important things to understand about credentials:

• Where they’re stored
• How the master key works
• How editing credentials work
• What the deal is with secrets.yml
• The steps you need to take to set up credentials on a fresh production machine

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 by default

A key thing to understand, which I found counterintuitive, is that unless you go out of your way to configure it differently, 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.

(After I originally posted this article, it was pointed out to me that it is possible to configure different keys per environment. According to this article, keys can be configured specific to e.g. production by running rails credentials:edit --environment production.)

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 a Vim 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.