skip to content

In Rails 8.1, how do per-environment credentials files work, and which key must a production server have to decrypt them?

level: middleimportance: must knowfreq 58%

answer

  1. edit with --environment or -e
  2. config/credentials/production.yml.enc
  3. replaces the global file, no merge
  4. RAILS_MASTER_KEY beats any key file
  5. production.key, not master.key

basics

~10 s

bin/rails credentials:edit -e production writes config/credentials/production.yml.enc with its own production.key. When that file exists, production reads it instead of credentials.yml.enc, without merging, so the server's RAILS_MASTER_KEY must hold production.key's value.

solid answer

~30 s

Running `bin/rails credentials:edit --environment production` (alias `-e`) creates `config/credentials/production.yml.enc` and `config/credentials/production.key`. At boot Rails sets `config.credentials.content_path` to `config/credentials/#{Rails.env}.yml.enc` when that file exists, otherwise to `config/credentials.yml.enc`, and `key_path` to `config/credentials/#{Rails.env}.key`, otherwise `config/master.key`. The environment file **replaces** the global one; nothing is merged, so shared values must be repeated. The key comes from `ENV["RAILS_MASTER_KEY"]` first, then the key file, so on a server that variable must contain `production.key`'s value, not `master.key`'s. A staging environment works the same way once `config/environments/staging.rb` exists and the server runs with `RAILS_ENV=staging`; it then needs its own key.

code

bash · 13 lines
bash
# Create or edit staging and production credentials
bin/rails credentials:edit -e staging
bin/rails credentials:edit -e production

# Resulting files
# config/credentials/staging.yml.enc     (commit)
# config/credentials/staging.key         (git-ignored)
# config/credentials/production.yml.enc  (commit)
# config/credentials/production.key      (git-ignored)

# On a production server
# RAILS_ENV=production
# RAILS_MASTER_KEY=<contents of config/credentials/production.key>

go deeper

for a junior

Recall the -e flag, the config/credentials/<env>.yml.enc path, and that each environment has its own key file.

for a middle

Explain the content_path and key_path fallbacks, the lack of merging, and why RAILS_MASTER_KEY must hold the environment's key.

for a senior

Diagnose nil-only-in-production and decryption failures on deploy, and set up a real staging environment with its own credentials.

for a principal

Weigh one shared file against per-environment files for access control, onboarding and rotation across a team.

## Why per-environment files exist With a single `config/credentials.yml.enc`, every developer who has `master.key` can read the production secrets. **Environment-specific credentials** split that: each environment can have its own encrypted file and its own key, so the people and machines that need staging secrets never hold production's key. ## Creating them ```bash bin/rails credentials:edit --environment production bin/rails credentials:edit -e staging ``` For each environment Rails writes: - `config/credentials/<env>.yml.enc`, the encrypted YAML; - `config/credentials/<env>.key`, a new key with mode 0600, added to `.gitignore` through a `/config/credentials/*.key` entry. Files for `production` and custom environments get a generated `secret_key_base`; files for `development` and `test` do not, because those environments can fall back to a local secret. ## How Rails picks the file at runtime `config.credentials` is set from two defaults that depend on `Rails.env`: | Setting | First choice | Fallback | |---|---|---| | `content_path` | `config/credentials/#{Rails.env}.yml.enc` if it exists | `config/credentials.yml.enc` | | `key_path` | `config/credentials/#{Rails.env}.key` if it exists | `config/master.key` | Two consequences matter in interviews: 1. **No merging.** Once `production.yml.enc` exists, production never reads `credentials.yml.enc`. A value you added only to the global file is nil in production. Repeat shared values in each file, or keep everything in the global file and have no environment file at all. 2. **The key follows the file.** The environment file is encrypted with its own key, so the master key cannot open it. Both paths can also be overridden with `config.credentials.content_path` and `config.credentials.key_path`. ## How the key reaches a server `ActiveSupport::EncryptedFile#key` tries, in order: 1. `ENV["RAILS_MASTER_KEY"]`, if present; 2. the file at `key_path`. The environment variable **wins over any key file**, including an environment-specific one. The variable keeps its name whatever the environment, so for a food-delivery app's production servers: - `RAILS_MASTER_KEY` must contain the contents of `config/credentials/production.key`; - a staging host needs the contents of `config/credentials/staging.key` in the same variable name; - the key files themselves never go into the repository or the image. How a deploy tool delivers that variable is the deploy tool's concern; Rails only reads it. ## Staging as its own environment A staging server that runs with `RAILS_ENV=production` reads production's file. To give staging its own credentials: 1. copy `config/environments/production.rb` to `config/environments/staging.rb` and adjust it; 2. add a `staging` entry to `config/database.yml` and any other per-environment YAML; 3. run `bin/rails credentials:edit -e staging` and put the staging mapping key there; 4. run the servers with `RAILS_ENV=staging` and the staging key in `RAILS_MASTER_KEY`. ## Common failures - **A value is nil only in production**: it was added to the global file after `production.yml.enc` was created. - **Decryption error on deploy**: `RAILS_MASTER_KEY` holds `master.key` while the server reads `production.yml.enc`, giving `ActiveSupport::MessageEncryptor::InvalidMessage`. - **Editing the wrong file**: `bin/rails credentials:edit` without `-e` edits whichever file the current `Rails.env` resolves to, normally the global one in development. ## What interviewers check - That you can name the paths, the `-e` flag and the lookup order. - That you know environment files replace rather than extend the global file. - That you can say which key a production server needs and where it comes from.

  • You added the mapping key to credentials.yml.enc and it works in development but is nil in production; why?
    The project has a `config/credentials/production.yml.enc`, so production reads only that file and never the global one. Environment files replace, not extend, the global file. Add the key with `bin/rails credentials:edit -e production`.
  • A server has both config/credentials/production.key on disk and a RAILS_MASTER_KEY variable; which one does Rails use?
    `RAILS_MASTER_KEY`. `EncryptedFile#key` reads the environment variable first and only falls back to the key file when the variable is absent or blank. If the variable holds a different key, decryption fails even though the right file is on disk.

  • production.yml.enc is merged over credentials.yml.enc at boot.
  • RAILS_MASTER_KEY is only consulted when no key file exists.
  • The master key decrypts every environment's credentials file.
  • A staging server with RAILS_ENV=production reads staging credentials.
  • Per-environment key files are committed because they are environment-specific.

Assumes Rails 8.1; per-environment credentials and the RAILS_MASTER_KEY precedence are older, while 8.1 broadened the generated .gitignore entry to cover every key file in the directory.