Rails 5.1 Encrypted secrets management

Before Rails 5.1, secrets management was a hassle. Gems like dotenv-rails, sekrets were being used to manage secrets in Rails applications. Rails 5.1 released secrets management feature based on sekrets gem. This article will explain how to manage application secrets with Rails 5.1 applications.

The problem with application secrets, is that they can not be added to VCS (Version control system). If added it exposes vulnerability of the secrets.

Before Rails 5.1

Developers used gems like dotenv-rails and sekrets to manage application secrets with Rails application.


dotenv-rails added support to have dotfiles like .env (in yml format) in the project. Key values defined in the yml file, were loaded into ENV variable. To have separate env files per environment, files like .env.development, .env.staging were created.

These files were gitignored. This way, these files were not added to VCS and the purpose of having secrets as secrets was solved. The production .env was kept on the production servers or pushed to production servers through any of the deployment tools.


Sekrets gem encrypts a file and encrypted file can be checked in VCS. The encryption key is not checked in VCS. Encryption key is made available on the staging / production servers.

Once the code is deployed, the encryption key is used to decrypt the encrypted file and load it in ENV variable. Rails 5.1 uses logic / workflow defined by sekrets gem for the secrets management that we will see next.

After Rails 5.1

Rails 5.1 added a feature to allow application secrets management.


To setup secrets with Rails 5.1 application, run the following command.

bin/rails secrets:setup

Running the command will do following things.

  • Generates an encryption key to encrypt application secrets.
  • Adds secrets.yml.key file with encryption key in config directory of the Rails application.
  • Gitignores secrets.yml.key in .gitignore file, so that it does not get checked in VCS.
  • Adds secrets.yml.enc file where encrypted secrets will be added and can be checked in.
Edit secrets

To edit secrets in Rails 5.1+ application, run the following command.

bin/rails secrets:edit

It needs an editor to be set for the editing of secrets. If editor is not set, it asks to set an editor as given below.

No $EDITOR to open decrypted secrets in. Assign one like this:

EDITOR="mate --wait" bin/rails secrets:edit

For editors that fork and exit immediately, it's important to pass a wait flag,
otherwise the secrets will be saved immediately with no chance to edit.

Using VIM for editing secrets,

EDITOR="vim" bin/rails secrets:edit

This will decrypt secrets.yml.enc and open up for editing.

# See `secrets.yml` for tips on generating suitable keys.
# production:
#  external_api_key: 1466aac22e6a869134be3d09b9e89232fc2c2289

Update the file and save it.

Reading the encrypted secrets

Rails application by default will not read the encrypted secrets in development environment.

Rails has added a new configuration flag to override this setting.

config.read_encrypted_secrets = true

The above flag is set to true in production environement by default.

These secrets are available to access in Rails application as given below.

  • Application secrets can be encrypted and checked in VCS from Rails 5.1+ application.
  • Secrets can be edited using the encryption key which is not checked in VCS.
  • Secret key should be checked in RAILS_MASTER_KEY environment variable or make secrets.yml.key available in the application through deployment.