Everything that involves a private key — SSH authentication to remotes, git
commit signing — flows through 1Password. There is no local ~/.ssh/id_*
private key, no GPG keyring, no gpg-agent. The 1Password app holds the
keys and answers signing/auth requests through its SSH agent socket.
This document explains the moving parts and how to recover when something breaks.
| Piece | Role | Installed by |
|---|---|---|
| 1Password Desktop | Hosts the SSH agent socket. Required for auth/signing to work. | apply-install (GUI environments only on Linux; always present on macOS) |
1Password CLI (op) |
Read items from the command line (my-key, scripts). |
apply-install (always — works without GUI) |
my-key |
Fetches the SSH key (public or private) from 1Password via op. |
Copied to ~/.bin/ by apply-files. See utilities.md. |
| SSH key (1Password item) | Used for both SSH auth and git signing. Item ID exported as OP_SSH_KEY_ID. |
Created manually in 1Password. |
1Password Desktop opens a Unix socket and listens for SSH-protocol messages.
Our shell config exports SSH_AUTH_SOCK pointing at that socket:
- macOS:
$HOME/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock - Linux (with GUI):
$HOME/.1password/agent.sock
Set in:
When ssh, git fetch, or ssh-keygen -Y sign runs, OpenSSH talks to that
socket; 1Password pops a confirmation dialog; the operation completes.
There is no private key in ~/.ssh/. The ~/.ssh/config references
IdentityAgent (path replaced by apply-files at copy time to handle the
macOS Group Container with spaces), so OpenSSH knows to always go through the
1Password agent.
Verify it is working:
echo $SSH_AUTH_SOCK # Should point at the 1Password socket
ssh-add -L # Should list your public key(s) — no prompt
ssh -T git@github.com # Should authenticate without passwordWe use git's native SSH signing (no GPG, no ~/.gnupg/).
[gpg]
format = ssh
[user]
signingkey = key::ssh-ed25519 AAAAC3NzaC1lZDI1NTE5...The key:: prefix tells git to use the inline string as the public key
instead of reading from a file. The public key is, well, public — versioning
it in the repository is safe.
commit.gpgsign is intentionally NOT set in .gitconfig-base. Instead,
apply-files appends it to ~/.gitconfig only when an SSH agent is reachable:
if ssh-add -L > /dev/null 2>&1; then
# …append [commit] gpgsign = true and [tag] gpgsign = true
fiThis means cloning the dotfiles on a headless server (no 1Password Desktop)
leaves git commit working — it just doesn't sign. On GUI machines with
1Password running, signing is enabled automatically.
git commitcalls the SSH signing program (default:ssh-keygen -Y sign).ssh-keygenuses thekey::inline pubkey to identify which key to ask the agent for.- The agent (1Password) prompts for confirmation (TouchID / Watch / system auth), produces a signature, returns it to git.
- Git embeds the signature in the commit object.
You don't have an allowed_signers file by default, so git log --show-signature will not be able to verify your own commits. To enable
verification, write a file like ~/.ssh/allowed_signers with:
your-email@example.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5... (same key)
And configure:
git config --global gpg.ssh.allowedSignersFile ~/.ssh/allowed_signersNot part of the base config because it duplicates the pubkey.
For GitHub to show commits as Verified, add the same SSH key under Settings → SSH and GPG keys, and pick the "Signing Key" type (not "Authentication Key" — you can add the same key twice with both roles).
echo $SSH_AUTH_SOCK # empty? agent socket is not exported
ls -la "$SSH_AUTH_SOCK" # missing? 1Password Desktop is not runningOpen 1Password Desktop, enable Settings → Developer → Use the SSH agent. Restart the shell.
git config --global gpg.format # → ssh
git config --global user.signingkey # → key::ssh-ed25519 …
git config --global commit.gpgsign # → true (set by apply-files if agent OK)
ssh-add -L # → lists your keyIf ssh-add -L shows the key but signing still fails, try the signing
operation directly:
echo test | ssh-keygen -Y sign -n git -f <(echo "ssh-ed25519 AAAAC3...")The error message from ssh-keygen is usually more informative than git's
generic "gpg failed to sign the data".
op account list # → empty if not signed in
op signin # → interactive sign-inAfter signing in, any script that uses op (like my-key, or the optional
commit-signing activation in apply-files) will work.
- Generate a new key in 1Password (let it manage the key material).
- Update
OP_SSH_KEY_IDinshared_shell_config-{macos,linux}if the item ID changed. - Replace the inline pubkey in
.gitconfig-base. - Run
./dotfiles apply:files. - Add the new pubkey to GitHub (both auth + signing roles) and any other remotes.
- Remove the old key from GitHub once you have confirmed signing works.