skip to content

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%

answer

  1. git textconv driver
  2. rails new enrolls unless --skip-decrypted-diffs
  3. .gitattributes diff=rails_credentials
  4. fetch PATH is new in 8.1
  5. dotted path, exit 1 when missing

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.

solid answer

~40 s

`bin/rails credentials:diff --enroll` appends `config/credentials/*.yml.enc diff=rails_credentials` and `config/credentials.yml.enc diff=rails_credentials` to `.gitattributes`; `credentials:edit` then configures `git config diff.rails_credentials.textconv` to call `bin/rails credentials:diff`, so `git diff` and `git log -p` show the decrypted YAML for files you have the key for and ciphertext otherwise. `rails new` enrolls unless you pass `--skip-decrypted-diffs`, and `--disenroll` reverses it. `bin/rails credentials:fetch maps.api_key`, added in 8.1, decrypts the file for the current environment (or `-e`), walks the dotted path and prints that one value, exiting 1 with "Invalid or missing credential path" when it is not there. That lets a deploy script pull a single secret without printing the whole file the way `credentials:show` does.

code

bash · 8 lines
bash
# Once per project (rails new already did this unless --skip-decrypted-diffs)
bin/rails credentials:diff --enroll

# Review the change with decrypted output
git diff main -- config/credentials/production.yml.enc

# Read a single value in a deploy script; exits 1 if the path is wrong
MAPS_KEY=$(bin/rails credentials:fetch -e production maps.api_key) || exit 1

go deeper

for a junior

Recall that credentials changes can be shown decrypted in git diff and that one value can be fetched from the command line.

for a middle

Explain the .gitattributes entries, the textconv driver set by credentials:edit, and fetch's dotted path and exit status.

for a senior

Design a review and deploy workflow that keeps secrets out of CI logs and catches a wrong path before traffic.

for a principal

Decide who should hold which environment's key, given that review of the change depends on holding it.

## The review problem An encrypted credentials file changes as one opaque blob. In a pull request that adds a mapping-service key to a food-delivery app, reviewers see a binary-looking change and cannot tell whether someone also deleted the payment key or pasted a staging value into production. Rails offers two commands that make the file workable in everyday tooling. ## `bin/rails credentials:diff`: readable diffs `credentials:diff` has two jobs. **Enrolling a project.** `bin/rails credentials:diff --enroll` appends two lines to `.gitattributes`: ``` config/credentials/*.yml.enc diff=rails_credentials config/credentials.yml.enc diff=rails_credentials ``` That tells git to use a diff driver named `rails_credentials` for those files. The driver itself lives in untracked git config, so Rails sets it up for each clone the next time someone runs `bin/rails credentials:edit`: ```bash git config diff.rails_credentials.textconv 'bin/rails credentials:diff' ``` **Acting as the driver.** When git calls `bin/rails credentials:diff <path>`, Rails works out the environment from the path, decrypts the file with the matching key and prints the YAML. If the key is missing or wrong, it prints the ciphertext instead, so the diff degrades rather than fails. Points to remember: - `rails new` enrolls the project automatically unless you pass `--skip-decrypted-diffs`. - `--disenroll` removes the `.gitattributes` lines. - Decrypted diffs appear only on machines that hold the key; a code-hosting site's web view still shows ciphertext. - The plain text appears in your terminal and pager, which matters when screen-sharing. ## `bin/rails credentials:fetch`: one value for a script Rails 8.1 added `bin/rails credentials:fetch PATH`: 1. it loads the environment (`-e production` selects `config/credentials/production.yml.enc`); 2. decrypts the YAML; 3. walks the dotted path, for example `maps.api_key`, with `fetch` at each level; 4. prints the value, or prints "Invalid or missing credential path: maps.api_key" and exits with status 1. Because it fails with a non-zero status, a deploy script stops instead of continuing with an empty variable. Rails' own release notes show it used to feed a deploy tool's secrets file, for example `KAMAL_REGISTRY_PASSWORD=$(rails credentials:fetch kamal.registry_password)`. It needs the key, like any other credentials command. ## How the commands compare | Command | Output | Typical use | |---|---|---| | `credentials:edit` | opens an editor, saves re-encrypted | changing values | | `credentials:show` | the whole decrypted file | checking a key works, reading by eye | | `credentials:fetch PATH` | one value, exit 1 if missing | scripts and deploy hooks | | `credentials:diff` | decrypted YAML for git, ciphertext without the key | code review | ## A review workflow for a new key 1. The author runs `bin/rails credentials:edit -e production`, adds `maps.api_key`, and commits. 2. A reviewer with the production key runs `git diff main -- config/credentials/production.yml.enc` and sees exactly one added line. 3. The deploy script runs `bin/rails credentials:fetch -e production maps.api_key` as a smoke check, failing the deploy if the path is wrong. 4. Reviewers without the key review the code that reads the value and trust the key holder's check of the YAML. ## Pitfalls - `credentials:fetch` prints the secret to standard output; avoid it in CI steps whose logs are public. - Fetching a section, such as `maps`, prints the Ruby hash's string form, not YAML. - Decrypted diffs do not solve merge conflicts in ciphertext; re-apply changes with `credentials:edit`. ## What interviewers check - That you know decrypted diffs exist, are on by default, and depend on holding the key. - That you can name `credentials:fetch` as the 8.1 way to read one value from a script, and its failure behaviour.

  • A reviewer runs git diff on a credentials change and sees base64 ciphertext; what is missing?
    Either the project is not enrolled (no `diff=rails_credentials` lines in `.gitattributes`), the driver is not configured in that clone's git config (running `bin/rails credentials:edit` once sets it), or the reviewer lacks the key for that file. In the last case `credentials:diff` deliberately falls back to printing ciphertext.
  • Why prefer credentials:fetch over parsing credentials:show output in a script?
    `show` prints the whole decrypted file, so a script would expose every secret to its logs and would need its own YAML parsing. `fetch` prints only the requested value and exits 1 with a clear message when the path is wrong, which a script can test.

  • credentials:diff decrypts the file for anyone, even without the key.
  • Decrypted diffs require each developer to install a separate git tool.
  • credentials:fetch has existed since credentials were introduced in 5.2.
  • credentials:fetch returns an empty string and exit 0 for a missing path.
  • Enrolling in decrypted diffs stores plain-text credentials in the repository.

Assumes Rails 8.1; credentials:fetch was added in 8.1, while decrypted diffs and default enrollment by rails new are older.