Configures git to sign commits using the SSH key forwarded from the host's SSH agent.
10K+
Configures git to sign commits using the SSH key forwarded from the host's SSH agent.
| Name | Required | Default | Description |
|---|---|---|---|
version | Required | — | Kit revision supplied by the DHI build |
| Type | Required | Description | |
|---|---|---|---|
com.docker.sandbox/git-identity@1 | Optional | — | |
com.docker.sandbox/ssh-agent@1 | Required | — | |
com.docker.sandbox/network-policy@1 | Required | — | |
com.docker.sandbox/lifecycle@1 | Required | — | |
com.docker.sandbox/agent-context@1 | Optional | — | |
com.docker.sandbox/agent-context@2 | Optional | — | |
deb/openssh-clientsbx run <agent> --kit sbx/git-ssh-sign:latestRun the following command to install sbx on your machine.
brew install docker/tap/sbxwinget install Docker.sbxThis v3 mixin Kit configures Git to sign commits and tags using the SSH key forwarded from your host's SSH agent. It composes with a compatible workload, including the Claude Code, Codex, and Cursor agent Kits.
This Kit is built on Docker Hardened Images.
Sandboxes forward your host's SSH agent automatically — the private key stays on your host. See Signed commits for the underlying mechanism this kit builds on.
On the host, load your SSH key into the agent:
ssh-add ~/.ssh/id_ed25519
Then start the sandbox with the kit attached, from its published OCI artifact on Docker Hub:
sbx run sbx/claude --kit sbx/git-ssh-sign ~/my-project
Inside the sandbox, verify that the forwarded agent exposes your key:
ssh-add -L
ssh-ed25519 AAAA... [email protected]
If it returns nothing, the key isn't loaded on the host yet — re-run ssh-add there and try again. Git signing fails
loudly, with a message naming the exact state and its recovery; see
When signing fails.
git log --show-signature -1
commit abc1234...
Good "git" signature for [email protected] with ED25519 key SHA256:...
Git surfaces a failed signature as two lines:
warning: gpg.ssh.defaultKeyCommand failed: [git-ssh-sign] ...
error: user.signingKey needs to be set for ssh signing
The second line is git's, not this kit's, and it is misleading — the kit leaves user.signingKey unset on purpose. Git
prints the key command's stderr verbatim in the warning: line above it, so the [git-ssh-sign] lines are the ones
that name the real state and its fix.
Inside the sandbox, confirm which state you are in:
echo "$SSH_AUTH_SOCK" # always set in a sandbox — proves nothing on its own
test -S "$SSH_AUTH_SOCK" # the real check: is the relay socket present?
ssh-add -l # 0 = keys loaded; 1 = connected but no usable key; 2 = no connection
SSH_AUTH_SOCK is exported into every sandbox whether or not agent forwarding was actually wired, so a set variable and
a missing socket are the common failure — the in-sandbox relay is not running.
Recovery happens on the host:
Check that forwarding is enabled at all:
sbx settings get ssh.agentForwardingEnabled # must be true
sbx settings set ssh.agentForwardingEnabled true
Check this before anything else. While it is false the forwarded agent is never wired up, so ssh-add in the
sandbox reports a broken agent (exit 1 or 2, depending on how far the connection gets) rather than a disabled
feature, and it survives any number of key reloads and sandbox restarts. It defaults to true, so false means
something turned it off, e.g. declining agent forwarding in sbx setup.
Check the host agent holds the key: ssh-add -l, then ssh-add ~/.ssh/id_ed25519 if it does not.
If step 1 changed the setting, restart the daemon: sbx daemon restart. Changes to ssh.agentForwardingEnabled and
ssh.agentSocketPath only reach sandboxes that already exist once the daemon has restarted.
From that same shell — the daemon adopts the requesting client's SSH_AUTH_SOCK — restart the sandbox's container so
the in-container relay is relaunched:
sbx stop <sandbox-name>
sbx run --name <sandbox-name>
Stop-then-run is the supported restart cycle; there is no sbx start. Substitute the sandbox's own name — hostname
prints it inside the sandbox, but $SANDBOX_NAME is not set in a host shell, so type the literal name there.
To get one commit through unsigned while you sort that out:
git -c commit.gpgsign=false commit -m "..."
See also Docker's troubleshooting guide.
Git signing requires two things to be available when Git signs the commit: signing config (what format to use and how to resolve a key) and the actual key material from the forwarded SSH agent.
Signing machinery — written at install time to /etc/gitconfig
The install command writes gpg.format, gpg.ssh.defaultKeyCommand, and gpg.ssh.allowedSignersFile to the
system-level git config, and makes sure user.signingKey stays unset. This file is read by git at process startup and
is never overwritten by the sandbox infrastructure, so the config is always present when git commit begins.
user.signingKey has to stay empty: git consults gpg.ssh.defaultKeyCommand only when it is unset. Setting it to any
value — even a placeholder meant to produce a nicer error — disables dynamic key resolution outright and breaks the
working case.
Signing policy — scoped to repositories that have a remote
commit.gpgSign and tag.gpgSign are not in /etc/gitconfig. They live in /etc/git/signing-enabled.inc, pulled in
conditionally:
[includeIf "hasconfig:remote.*.url:**"]
path = /etc/git/signing-enabled.inc
A machine-wide commit.gpgSign = true makes every git commit in the sandbox depend on a live SSH agent —
including throwaway repositories that test suites create with git init and that have nothing to do with your commits.
When the forwarded agent goes away, those all start failing too, with an error that points at user.signingKey. Scoping
by "has a remote" keeps automatic signing on in the repositories you push from, and off in local scratch repositories.
It is a proxy, not a guarantee: commits made in a fresh git init before the first git remote add stay unsigned and
are pushed that way.
Two things this deliberately does not do:
gitdir: to the workspace path. A sandbox can mount more than one host directory, and
repositories cloned inside the sandbox would fall outside any single workspace prefix.git commit -S still signs in any repository, scope or no scope, because the machinery above is machine-wide.
includeIf "hasconfig:…" needs git ≥ 2.36. The install command probes for it against a throwaway repository rather than
parsing a version string; on an older git it falls back to machine-wide commit.gpgSign so the kit fails closed (signs
too much) rather than open (signs nothing).
Key material — resolved at signing time
gpg.ssh.defaultKeyCommand runs /home/agent/.config/git/ssh-signing-key-command, a static script shipped as an
executable OCI overlay file owned by uid 1000. The install hook retains /bin/sh <path> so the same command works with
older artifacts.
When Git needs a signing key, it runs that command. The command picks a public key from ssh-add -L (see below), writes
/home/agent/.config/git/allowed_signers for signature verification, and prints the key in Git's inline key::...
format.
This avoids writing key material at install or startup time, when the forwarded SSH agent may not be connected yet. It also avoids relying on Git hooks for signing.
Picking which forwarded key to sign with
A host's SSH agent often forwards more than one key — e.g. a password manager's own key alongside the key you actually
use with GitHub — and nothing about ssh-add -L's ordering says which one is registered anywhere. Signing with the
wrong one still produces a valid signature, but it shows Unverified on GitHub because that key was never added to
the committer's account.
When the repo's remote is on github.com and the gh CLI is authenticated (gh auth status), the command instead:
gh api user).GET /users/{username}/ssh_signing_keys
endpoint — deliberately not github.com/{username}.keys, which only lists authentication keys and can diverge
from the signing-key list.The fallback writes a warning to stderr, but git only echoes the key command's stderr in the
gpg.ssh.defaultKeyCommand failed: line, which it prints when the command exits non-zero — so on the fallback path
the commit signs and looks entirely normal. Run the command by hand to see it:
/bin/sh ~/.config/git/ssh-signing-key-command
The GitHub response is cached for 5 minutes in /home/agent/.config/git/github-signing-keys.cache, since this command
runs on every single commit and signature and unauthenticated GitHub API requests are capped at 60/hour per source IP.
On any other remote host, or without gh, this step is skipped entirely: no network call is made and the command signs
with the first key the agent offers. GitHub Enterprise Server and other forges aren't cross-checked.
Author identity
The Kit requests git-identity@1 for runtime-provided user.name and user.email defaults. The runtime selects the
identity according to your settings and its policy. Repository-local Git identity settings retain normal precedence.
GitHub shows a signed commit as Verified only when its committer email belongs to the account that registered the
signing key. The request is optional, so the sandbox still starts when no runtime-provided identity is available.
Composing with repo-local hooks
This kit does not set core.hooksPath and does not install a pre-commit hook. Project-level hooks, hook managers, and
repo-local core.hooksPath settings can run independently of commit signing.
To also enable SSH push/pull to GitHub from the sandbox, combine this kit with github-ssh:
sbx run sbx/claude --kit sbx/git-ssh-sign --kit sbx/github-ssh
The forwarded agent may sign only in the git namespace. This kit grants no SSH authentication. Git attribution is an
optional, config-less runtime binding; repository and user configuration retain normal Git precedence. There are no
CREATE-time kit arguments. Node is not required; the workload must provide OpenSSH, in addition to the v3 platform
floor.
See the Sandbox Kit v3 specification for the Kit format and capability contracts.