131 lines
3.6 KiB
Markdown
131 lines
3.6 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
op signin
|
|
```
|
|
|
|
3. **jq installed**: For JSON parsing (included in base.txt)
|
|
|
|
## Setup
|
|
|
|
The credential helper is automatically configured in your `.gitconfig`:
|
|
|
|
```ini
|
|
[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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# Test the credential helper directly
|
|
echo -e "protocol=https\nhost=github.com\n" | ~/.dotfiles/scripts/git-credential-1password.sh get
|
|
```
|
|
|
|
## 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
|