Skip to main content

GitHub SSH Setup with 1Password

How to set up SSH key authentication for GitHub using 1Password as the SSH agent. The private key never touches disk — 1Password manages it.

Prerequisites​

SSH keys are stored in the Shared-Infrastructure vault — this is where all infra-level credentials live (SSH keys, PATs, server details). See vps-setup.md for the full vault structure and secret storage conventions.

How It Works​

git push → SSH → 1Password SSH Agent → signs with private key → GitHub verifies public key
  1. 1Password stores the SSH private key (never on disk)
  2. 1Password's SSH agent provides the key to SSH on demand
  3. ~/.ssh/config tells SSH to use 1Password's agent for github.com
  4. GitHub has the matching public key on your account

Setup Steps​

1. Enable 1Password SSH Agent​

In the 1Password desktop app:

  • Settings → Developer → Turn on SSH Agent
  • This creates the agent socket at: ~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock

2. Register the Key in the SSH Agent Config​

The 1Password SSH agent only serves keys that are explicitly listed in its config file:

~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.toml

Add an entry for your key:

[[ssh-keys]]
item = "GitHub SSH Key"
vault = "Shared-Infrastructure"

Keys are offered to SSH servers in the order they appear in this file. You can verify which keys the agent is serving:

SSH_AUTH_SOCK=~/Library/Group\ Containers/2BUA8C4S2C.com.1password/t/agent.sock ssh-add -l

By default, only keys in the Private vault are enabled. Keys in other vaults (like Shared-Infrastructure) must be added to agent.toml or they won't be offered.

3. Create an SSH Key in 1Password​

op item create \
  --category=sshkey \
  --title="GitHub SSH Key" \
  --vault="Shared-Infrastructure" \
  --ssh-generate-key=ed25519

Note the public key from the output (starts with ssh-ed25519 AAAA...).

4. Add the Public Key to GitHub​

gh ssh-key add <(echo "ssh-ed25519 AAAA...your-key-here...") --title "GitHub SSH Key (1Password)"

Or manually: GitHub → Settings → SSH and GPG keys → New SSH key.

5. Configure SSH​

Add a Host github.com block to ~/.ssh/config (before any Host * block):

Host github.com
  User git
  IdentityAgent "~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock"

If you don't already have a catch-all IdentityAgent, add it:

Host *
  IdentityAgent "~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock"

6. Add GitHub's Host Key​

Fetch the host key and verify its fingerprint before trusting it:

# Fetch the key to a temp file
ssh-keyscan github.com > /tmp/github_host_key 2>/dev/null

# Verify the fingerprint matches GitHub's published fingerprints
# See: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/githubs-ssh-key-fingerprints
ssh-keygen -lf /tmp/github_host_key

# If the fingerprint matches, add it
cat /tmp/github_host_key >> ~/.ssh/known_hosts
rm /tmp/github_host_key

7. Test​

ssh -T git@github.com
# Expected: Hi <username>! You've successfully authenticated...

8. Set Git Remotes to SSH​

# New repos
git remote add origin git@github.com:username/repo.git

# Existing repos (switch from HTTPS to SSH)
git remote set-url origin git@github.com:username/repo.git

# Set gh CLI to use SSH
gh config set git_protocol ssh

Troubleshooting​

ProblemFix
Permission denied (publickey)Open 1Password app → make sure SSH agent is enabled and the key is in an accessible vault
Host key verification failedRun ssh-keyscan -t ed25519 github.com > /tmp/gh_host && ssh-keygen -lf /tmp/gh_host — verify the fingerprint against GitHub's docs, then cat /tmp/gh_host >> ~/.ssh/known_hosts
ssh -T hangsCheck that the IdentityAgent path is correct and 1Password is running
Key not offeredCheck agent.toml — the key must be listed there. Run ssh-add -l to verify. If empty, the agent isn't serving any keys.

Current Configuration​

  • Key: "GitHub SSH Key" in Shared-Infrastructure vault (ed25519)
  • GitHub account: langhalsb
  • SSH config: ~/.ssh/config with Host github.com block
  • Agent socket: ~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock
  • gh CLI protocol: SSH (gh config set git_protocol ssh)

Why ed25519?​

All SSH keys use the ed25519 algorithm (Edwards-curve Digital Signature Algorithm on Curve25519). Compared to RSA: shorter keys, faster signing, no known weaknesses. It's the modern default.

  • VPS Setup — full VPS provisioning guide, 1Password vault structure, and secret storage conventions