Skip to content

docs(git): document macOS osxkeychain conflict and URL-scoped helper setup #4229

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jdrolls wants to merge 1 commit into
base: main
Choose a base branch
from
+34 −0
Open

docs(git): document macOS osxkeychain conflict and URL-scoped helper setup #4229

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions crates/git-credential-nostr/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,39 @@ git config --global nostr.keyfile ~/.nostr/key

That's it. Use git normally — `git clone`, `git push`, `git fetch`.

### macOS: scope the helper to your relay

On macOS, Xcode's bundled gitconfig registers `osxkeychain` as a credential
helper for every repository:

```
$ git config --show-origin --get-all credential.helper
file:/Applications/Xcode.app/Contents/Developer/usr/share/git-core/gitconfig osxkeychain
```

`git config --global credential.helper nostr` **appends** to that chain rather
than replacing it. Both helpers run, and after each successful operation git
asks every helper in the chain to store the credential — osxkeychain cannot
store the Nostr credential shape and prints:

```
failed to store: -1
```

Operations still succeed; the error is pure noise. To silence it — and to keep
the helper from ever running for github.com or other hosts — register the
helper scoped to your relay URL instead of globally (the same idiom GitHub's
`gh` CLI uses):

```bash
git config --global --add credential.https://relay.example.com.helper "" # reset the chain for this URL
git config --global --add credential.https://relay.example.com.helper nostr
git config --global credential.useHttpPath true
```

The empty first entry resets the helper chain for that URL, so only `nostr`
runs against your relay and osxkeychain keeps handling everything else.

## CI / CD

Set `$NOSTR_PRIVATE_KEY` instead of a key file. The env var takes precedence
Expand Down Expand Up @@ -66,4 +99,5 @@ git ──stdin──▶ git-credential-nostr ──stdout──▶ git
| `method hint` | Server's `WWW-Authenticate` header is missing `method="..."` | Upgrade the Buzz server |
| `useHttpPath` | `credential.useHttpPath` is not set | `git config --global credential.useHttpPath true` |
| Empty output / no auth | git version is older than 2.46 | Upgrade git |
| `failed to store: -1` after successful operations (macOS) | Xcode's global `osxkeychain` helper runs alongside `nostr` and can't store the Nostr credential | Scope the helper to your relay URL — see [macOS](#macos-scope-the-helper-to-your-relay) |
| `clock skew` / auth rejected | System clock is off by more than 60 s | Sync your system clock (`ntpdate`, `timedatectl`) |