dotfiles/docs/git-1password-setup.md

Git + 1Password HTTPS Credential Helper

This setup allows Git to automatically fetch HTTPS credentials from 1Password without storing them locally.

Prerequisites

1. 1Password CLI installed: The op command should be available

   • On Ubuntu/Debian: Install from 1Password's official repository
   • Package name: 1password-cli (included in base.txt)

2. 1Password CLI authenticated: You must be signed in to 1Password CLI

   op signin
   

3. jq installed: For JSON parsing (included in base.txt)

Setup

The credential helper is automatically configured in your .gitconfig:

[credential]
helper = !~/.dotfiles/scripts/git-credential-1password.sh

Usage

Storing Credentials in 1Password

For each Git HTTPS remote you want to use, create an item in 1Password with:

1. Title: Include the hostname (e.g., "GitHub", "gitlab.example.com", "bitbucket.org")
2. Username field: Your Git username
3. Password field: Your Git password/token
4. URL field (optional but recommended): The full HTTPS URL of the repository

Examples:

GitHub Personal Access Token:

• Title: "GitHub"
• Username: your-github-username
• Password: ghp_xxxxxxxxxxxxxxxxxxxx
• URL: https://github.com

GitLab Token:

• Title: "gitlab.example.com"
• Username: your-gitlab-username
• Password: glpat-xxxxxxxxxxxxxxxxxxxx
• URL: https://gitlab.example.com

Using with Git

Once set up, Git operations will automatically prompt 1Password for credentials:

# Clone a private repo
git clone https://github.com/user/private-repo.git

# Push to origin
git push origin main

# Add a new HTTPS remote
git remote add upstream https://github.com/upstream/repo.git

How It Works

1. When Git needs HTTPS credentials, it calls the credential helper
2. The helper searches 1Password for items matching the hostname
3. It looks for matches in:
   • URL fields containing the hostname
   • Item titles containing the hostname
   • Additional information containing the hostname
4. Returns the username and password to Git
5. Git uses these credentials for the operation

Troubleshooting

"1Password CLI (op) not found"

Install 1Password CLI or ensure it's in your PATH:

# Check if installed
which op

# Install if missing (Ubuntu/Debian)
curl -sS https://downloads.1password.com/linux/keys/1password.asc | sudo gpg --dearmor --output /usr/share/keyrings/1password-archive-keyring.gpg
echo 'deb [arch=amd64 signed-by=/usr/share/keyrings/1password-archive-keyring.gpg] https://downloads.1password.com/linux/debian/amd64 stable main' | sudo tee /etc/apt/sources.list.d/1password.list
sudo apt update && sudo apt install 1password-cli

"Not signed in to 1Password CLI"

Sign in to 1Password CLI:

op signin

"No matching item found"

• Ensure the 1Password item title or URL contains the Git hostname
• Check that the item has username and password fields
• Try creating a new item with a clear title matching the hostname

Test the Helper Manually

# Test the credential helper directly
echo -e "protocol=https\nhost=github.com\n" | ~/.dotfiles/scripts/git-credential-1password.sh get

# Debug: List all 1Password items to see what's available
op item list --format=json | jq -r '.[] | "\(.title) - \(.id)"'

# Debug: See the structure of a specific item
op item get "YOUR_ITEM_ID" --format=json | jq

# Debug: Check what fields are available in an item
op item get "YOUR_ITEM_ID" --format=json | jq -r '.fields[] | "\(.label // .id): \(.value // "empty")"'

Common Issues

jq null matching errors:

• This happens when 1Password items have missing fields
• The updated script handles null values gracefully
• Make sure your items have proper username and password fields

Field naming issues:

• The script looks for fields with labels containing: "username", "user", "login"
• For passwords, it looks for: "password", "token", "secret", "pass"
• If your fields have different names, rename them in 1Password

Security Benefits

• Credentials are never stored in plain text on disk
• Works with 1Password's security features (Touch ID, master password, etc.)
• Credentials are fetched fresh each time (no caching)
• Works seamlessly with existing 1Password setup

Limitations

• Only works with HTTPS Git remotes (SSH remotes continue to use SSH keys)
• Requires 1Password CLI to be signed in
• May prompt for 1Password unlock depending on your security settings