skip to content

Credentials & Master Key

Rails keeps secrets in config/credentials.yml.enc, decrypted by master.key or RAILS_MASTER_KEY, and derives signing keys from secret_key_base. Interviewers probe deploys, per-env files and leaks.

part ofRuby on Railsread it →
on this pageshow

explore

questions

5

In a Rails 8.1 app, how do you add a mapping-service API key to the encrypted credentials, and how does application code read it?

level: juniorimportance: must knowfreq 74%

answer

  1. an encrypted YAML file in config/
  2. bin/rails credentials:edit opens $EDITOR
  3. master.key decrypts, and it is git-ignored
  4. credentials.dig(:maps, :api_key)
  5. bang accessor raises KeyError when blank

basics

~10 s

Run bin/rails credentials:edit, which decrypts config/credentials.yml.enc with config/master.key into your editor and re-encrypts it on save. Code reads Rails.application.credentials.dig(:maps, :api_key), or the bang accessor to fail on a blank value.

solid answer

~30 s

`bin/rails credentials:edit` opens a temporary decrypted copy of `config/credentials.yml.enc` in `$VISUAL` or `$EDITOR`; when you save and close, Rails encrypts the YAML again with the key from `RAILS_MASTER_KEY` or `config/master.key` and deletes the temporary file. You add something like `maps: { api_key: ... }`. The encrypted file is committed; `master.key` is generated by `rails new` and git-ignored, and the team shares it through a password manager. At runtime `Rails.application.credentials` returns an `ActiveSupport::EncryptedConfiguration` with symbolized keys: `credentials.dig(:maps, :api_key)` and `credentials.maps.api_key` return nil when missing, `credentials.maps.api_key!` raises `KeyError` when the value is blank, and `credentials.fetch(:maps)` raises `KeyError` when the key is absent.

code

yaml · 6 lines
yaml
# Decrypted view inside bin/rails credentials:edit
maps:
  api_key: mk_live_9f2c...
  account_id: courier-routing

secret_key_base: 3b7c...

go deeper

for a junior

Recall the two files, which one is committed, and that bin/rails credentials:edit is the only way to change them.

for a middle

Explain the edit cycle, the key lookup order, and the difference between dig, the dynamic accessor, fetch and the bang accessor.

for a senior

Show judgement about failing fast on required secrets, avoiding leaks through credentials:show, and handling merge conflicts in ciphertext.

for a principal

Discuss when an encrypted file in the repository stops scaling and a central secret store becomes worth its operational cost.

## What Rails credentials are **Credentials** are Rails' built-in place for secrets such as API keys, SMTP passwords and `secret_key_base`. They live in one YAML document that is stored **encrypted** in the repository, so the secret travels with the code but cannot be read without a key. A new Rails 8.1 app gets two files from `rails new`: - `config/credentials.yml.enc`, the encrypted YAML (AES-128-GCM), committed to git; - `config/master.key`, 32 hexadecimal characters that decrypt it, written with file mode 0600 and added to `.gitignore` (in 8.1 the ignore entry covers every `*.key` file in that directory). `rails new` prints a reminder to store the key in a password manager the team can reach, because without it nobody can decrypt the file again. ## Editing: `bin/rails credentials:edit` For a food-delivery app that needs a key for its mapping service: 1. Run `EDITOR="code --wait" bin/rails credentials:edit` (any editor that blocks until the file is closed works). 2. Rails reads the key, preferring `ENV["RAILS_MASTER_KEY"]` over `config/master.key`, decrypts the file into a temporary path and opens it. 3. You add the value and save. Rails encrypts the content, writes `credentials.yml.enc`, removes the temporary file and then checks that the YAML parses. 4. You commit the changed `.yml.enc`; the diff is ciphertext unless the project is enrolled in decrypted diffs. If the YAML is invalid, Rails warns that the app will not be able to load the file until it is fixed. If the key is wrong, it says it could not decrypt the file and changes nothing. ## Reading values in code `Rails.application.credentials` is an `ActiveSupport::EncryptedConfiguration`. It decrypts once, symbolizes keys and offers several ways in: | Call | Missing key | Blank value | |---|---|---| | `credentials.dig(:maps, :api_key)` | `nil` | the blank value | | `credentials.maps.api_key` | `nil` (or `NoMethodError` if `maps` itself is missing) | the blank value | | `credentials.maps.api_key!` | `KeyError` | `KeyError` (`":api_key is blank"`) | | `credentials.fetch(:maps)` | `KeyError` | the value | | `credentials[:maps]` | `nil` | the value | The bang accessor comes from `ActiveSupport::OrderedOptions`, which Rails builds for each nested hash. It is the idiomatic way to fail loudly when a required secret is missing, for example in an initializer: ```ruby MapsClient.api_key = Rails.application.credentials.maps.api_key! ``` `dig` is the safe choice for optional values, because a missing intermediate key returns nil instead of raising `NoMethodError` on nil. ## What is safe to commit and what is not - **Commit** `config/credentials.yml.enc`: without the key it is unreadable ciphertext. - **Never commit** `config/master.key`; anyone holding it plus the repository can read every secret. - **Do not paste** decrypted output from `bin/rails credentials:show` into tickets or logs; it prints the whole file. ## Where it stops Credentials are read when the app runs, from the key available on that machine. A server therefore needs the key, usually as `RAILS_MASTER_KEY` in its environment. Per-environment files and how the key reaches a server are the natural next questions. ## What interviewers check - That you edit with `bin/rails credentials:edit`, never by hand. - That you know which file is committed and which is secret. - That you can read a nested value and choose between `dig` and the bang form.

  • Why might `Rails.application.credentials.maps.api_key` raise NoMethodError while `dig(:maps, :api_key)` returns nil?
    If the `maps` section is missing, `credentials.maps` returns nil, and calling `api_key` on nil raises `NoMethodError`. `dig` walks the hash and returns nil at the first missing level. Use `dig` for optional values and the bang accessor, `maps.api_key!`, when the section is known to exist and the value is required.
  • A colleague edits credentials.yml.enc on another branch at the same time; how do you resolve the merge conflict?
    Ciphertext cannot be merged line by line. Take one side's file, run `bin/rails credentials:edit`, and re-add the other branch's values by hand, reading them from that branch with the key. Keeping each change small and merging quickly avoids most conflicts.

  • Commit config/master.key so new developers can boot the app.
  • Edit config/credentials.yml.enc directly in the editor and commit it.
  • credentials.dig raises KeyError when the key is missing.
  • Credentials are decrypted at build time and baked into the app as plain YAML.
  • When RAILS_MASTER_KEY is set, Rails still prefers config/master.key.
open as a page

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%

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.

open as a page

A Rails 8.1 app deployed without RAILS_MASTER_KEY reads every credential as nil instead of failing; why, and what does config.require_master_key change?

level: middleimportance: should knowfreq 40%

basics

~10 s

With no key, Rails treats the credentials as an empty file, so every lookup returns nil until something like secret_key_base raises. config.require_master_key = true makes the first credentials read raise ActiveSupport::EncryptedFile::MissingKeyError instead.

open as a page

In a Rails 8.1 app, where does secret_key_base come from, what is derived from it, and what breaks if you replace it after a leak?

level: seniorimportance: should knowfreq 38%

basics

~20 s

secret_key_base comes from ENV['SECRET_KEY_BASE'], then credentials, then in development and test tmp/local_secret.txt. It seeds the key generator behind signed and encrypted cookies, cookie sessions and message verifiers, so replacing it invalidates them all unless old values are rotated in.

open as a page

In Rails 8.1, what do bin/rails credentials:diff and credentials:fetch do, and how do they help a team review and ship a new credential?

level: middleimportance: nice to knowfreq 22%

basics

~20 s

credentials:diff --enroll makes git diff show decrypted YAML to anyone holding the key; rails new enrolls by default. credentials:fetch, new in 8.1, prints one value by dotted path and exits 1 when it is missing.

open as a page