GPG Commit Signing

​

The problem this solves

#!/bin/bash
set -euo pipefail
echo "$gpg_key" | gpg --import
KEY_ID=$(echo "$gpg_key" | gpg --show-keys --with-colons | awk -F: '/^fpr/{print $10; exit}')
git config user.signingkey "$KEY_ID"
git config commit.gpgsign true
git config user.name "$git_user_name"
git config user.email "$git_user_email"

​

Why the hook can read the same secret as setup.sh

• git config --global instead of a bare git config. There is no repository yet when SessionStart fires, and a global config applies to every repo cloned afterwards.
• Never fails the session. SessionStart hooks cannot block, so on any problem (missing secret, bad key) the hook logs the reason to /tmp/openhands_gpg_setup.log and exits 0.

​

The secret

Secret names are configurable through the GPG_KEY_SECRET_NAME, GIT_USER_NAME_SECRET_NAME, and GIT_USER_EMAIL_SECRET_NAME environment variables if your org uses different names.

​

What’s in the box

gpg-signer/
├── .claude-plugin/
│   └── plugin.json                      # Plugin metadata
├── hooks/
│   ├── hooks.json                       # SessionStart hook (inline script)
│   └── scripts/
│       └── configure_gpg_signing.sh     # Readable reference copy of the inline script
└── skills/
    └── gpg-signer/
        └── SKILL.md                     # Docs the agent reads (auto-loaded)

​

The hook

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "command", "command": "…import key + git config --global…", "timeout": 30 }
        ]
      }
    ]
  }
}

1. SessionStart — runs once, when the conversation begins (no repo needed).
2. Reads the armored key from $gpg_key, imports it with gpg --batch --import.
3. Extracts the primary key fingerprint (gpg --show-keys --with-colons).
4. Sets user.signingkey, commit.gpgsign true, tag.gpgsign true, and gpg.program globally, plus the optional identity secrets.
5. Exits 0 always; all human-readable output goes to /tmp/openhands_gpg_setup.log (on a successful hook, stdout is parsed as JSON, so it is kept clean).

Why the script is inlined (and mirrored in hooks/scripts/). When this runs as a plugin, hooks execute with the working directory set to the agent’s workspace (not the plugin directory), and there is no plugin-root path variable — so command cannot point at a bundled hooks/scripts/*.sh. The runnable copy is therefore inlined in hooks.json; hooks/scripts/configure_gpg_signing.sh is a readable reference that mirrors it. Edit the reference first, then mirror it into hooks.json. (Same pattern as the workspace-isolation example.)

​

Try it

​

Option 1: Load via API

cd ../load-plugin
python load_plugin.py \
  --repo-path gpg-commit-signing/gpg-signer \
  --secret gpg_key="$(gpg --armor --export-secret-keys you@example.com)" \
  --secret git_user_name="Your Name" \
  --secret git_user_email="you@example.com" \
  --message "Show me the output of: git config --global --get commit.gpgsign and git config --global --get user.signingkey"

# Expected: commit.gpgsign=true and user.signingkey=<fingerprint>

If you have already stored gpg_key as a user-level secret, the --secret flags are unnecessary — the hook will pick it up automatically.

​

Option 2: Launch via badge

Note: Replace ref: main with your branch name if testing before merge.

​

Verifying a signed commit

git clone https://github.com/octocat/Hello-World && cd Hello-World
echo "test" >> README && git commit -am "signed test"
git log --show-signature -1     # -> "Good signature from ..."

​

Hook types

​

Related

• OpenHands Hooks Guide — repository .openhands/hooks.json format
• Hooks (SDK guide) — programmatic hooks
• load-plugin — programmatic plugin loading (and passing per-conversation secrets)
• per-conversation-secrets — how secrets reach a conversation
• command-blacklist / command-whitelist / workspace-isolation — other hook examples