Secrets & macOS Keychain

Your dotfiles live in a git repo. That repo should never contain secrets — API tokens, passwords, private keys. But your configs often need those values. Chezmoi solves this by pulling secrets from your system's keychain at apply time, so the actual values never touch your source state.

Why Secrets Must Stay Out of the Source State

The source state is a git repo. Even if it's private, secrets in git are dangerous:

• Git history is forever — a deleted secret is still in the log
• You might switch to a public repo later
• Backup tools, CI, or collaborators could access it
• A single leaked commit exposes everything

The rule is simple: templates reference secrets by name, never by value. The actual secret lives in a secure store (Keychain, 1Password, etc.) and is injected only when chezmoi renders the template.

How It Works

Chezmoi uses the keyring template function to read from macOS Keychain (via the go-keyring library). On macOS this maps directly to Keychain Access. On Linux it uses GNOME Keyring, and on Windows it uses Credentials Manager.

The keyring Function

The template function signature is:

{{ keyring "service-name" "account-name" }}

This reads a password from the keychain matching the given service and account. You set values using chezmoi's CLI:

chezmoi secret keyring set --service=github --user=your-username

Chezmoi will prompt you for the value. It gets stored in macOS Keychain — you can verify it appears in Keychain Access.app under the service name you chose.

To retrieve it from the command line (useful for debugging):

chezmoi secret keyring get --service=github --user=your-username

Exercise: Store and Use a Secret

Step 1: Add a dummy secret to Keychain

You can use chezmoi's built-in command, or the macOS security CLI directly. Let's use chezmoi since that's what you'll use in practice:

chezmoi secret keyring set --service=chezmoi-lesson --user=demo-token

When prompted, type my-super-secret-value and press Enter.

security add-generic-password -s "chezmoi-lesson" -a "demo-token" -w "my-super-secret-value"

Step 2: Create a template that uses the secret

Create a chezmoi-managed file that references the keychain value:

chezmoi edit ~/.config/demo-secret.env

Add this content:

# This file is managed by chezmoi — do not edit directly.
DEMO_TOKEN={{ keyring "chezmoi-lesson" "demo-token" }}

Step 3: Preview the rendered output

chezmoi cat ~/.config/demo-secret.env

You should see:

# This file is managed by chezmoi — do not edit directly.
DEMO_TOKEN=my-super-secret-value

The secret is injected at render time. If you look at the source state, you'll only see the {{ keyring ... }} call — never the actual value.

Step 4: Apply and verify

chezmoi apply ~/.config/demo-secret.env
cat ~/.config/demo-secret.env

The target file contains the real secret. The source state stays clean.

Step 5: Clean up

chezmoi forget ~/.config/demo-secret.env
rm ~/.config/demo-secret.env
security delete-generic-password -s "chezmoi-lesson" -a "demo-token"

Real-World Example: GitHub Token in .gitconfig

Here's how you'd actually use this for a GitHub personal access token:

# Store the token
chezmoi secret keyring set --service=github --user=your-github-username

Then in your .gitconfig template (dot_gitconfig.tmpl):

[user]
    name = Your Name
    email = you@example.com

[github]
    user = {{ .github.user | quote }}
    token = {{ keyring "github" .github.user | quote }}

The | quote pipe wraps the value in quotes, which is good practice for values that might contain special characters.

Other Password Managers

Chezmoi integrates with many secret backends beyond Keychain. If you use one of these, the same principle applies — templates reference secrets by name:

Each manager has its own setup and authentication flow. The chezmoi docs cover each one in detail. For this course, we focus on Keychain since it's built into macOS and requires no extra software.

Knowledge Check

Next Up

Your source state is getting more sophisticated — templates, scripts, and now secrets pulled from Keychain. But not every file belongs in chezmoi. In Lesson 6: Ignore & Exclude, you'll learn to control what chezmoi tracks and what it leaves alone, keeping your source state focused.