Git Signing

Alien Agent ID signs every git commit with the agent’s Ed25519 key and attaches provenance trailers tracing back to the agent and its human owner. Proof bundles embedded as git notes make verification fully self-contained.

Setup

Git signing is configured automatically during bootstrap. To configure manually:


node cli.mjs git-setup --email user@example.com

This configures:

gpg.format = ssh — use SSH keys for signing
user.signingkey — path to agent’s SSH private key
commit.gpgsign = true — sign all commits by default
gpg.ssh.allowedSignersFile — for local signature verification

Use --global to apply the config globally instead of per-repo.

Making Signed Commits

Option A: `git-commit` (Recommended)


node cli.mjs git-commit --message "feat: implement auth flow"

This creates a commit that is:

SSH-signed with the agent’s Ed25519 key
Tagged with trailers linking to the agent’s identity and human owner
Logged in the audit trail with a hash-chained signed record
Proof-bundled as a git note (refs/notes/agent-id) for external verification

Push Commits and Proof Notes


node cli.mjs git-commit --message "feat: implement auth flow" --push

The --push flag pushes both the commit and proof notes to the remote, handling note ref merging automatically.

Option B: Normal `git commit`

Since git-setup sets commit.gpgsign = true, any git commit will be SSH-signed. However, it won’t include Alien Agent ID trailers or proof notes.

Commit Trailers

Every commit made with git-commit includes these trailers:

Trailer	Description
`Agent-ID-Fingerprint`	SHA-256 hash of the agent’s public key — unique agent identity
`Agent-ID-Owner`	AlienID address of the human who authorized this agent
`Agent-ID-Binding`	UUID of the cryptographic owner binding
`Co-Authored-By`	Agent identity (Alien Agent) — the commit author remains the human owner

The commit author is the human owner (from your git config), while the agent is credited as a co-author. This ensures compatibility with deployment platforms like Vercel that require the commit author to have project access.

Example commit message:


feat: implement auth flow

Agent-ID-Fingerprint: 945d41991dac118776409673019ed0fba36e13fc9d6b5534145f9e31128a3ec6
Agent-ID-Owner: 00000003010000000000539c741e0df8
Agent-ID-Binding: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Co-Authored-By: Alien Agent <alienagentid@eti.co>

GitHub Verified Badge

To get the “Verified” badge on GitHub commits:

After bootstrap, copy the SSH public key from the git-setup output
Go to GitHub → Settings → SSH and GPG keys → New SSH key
Set Key type to Signing Key
Paste the public key and save

Verifying Provenance


node cli.mjs git-verify --commit HEAD

The verification traces the full chain:

SSH signature — commit is signed, verified against the agent’s public key from the proof note
Agent fingerprint — public key hash matches the Agent-ID-Fingerprint trailer
Owner binding — Ed25519-signed by the agent, links agent to human owner
id_token hash — binding contains the hash of the SSO id_token, proving they’re linked
SSO attestation — id_token RS256 signature verified against Alien SSO’s JWKS

Online Verification

You can verify whether a commit is signed by an Alien Agent ID using the online verification service:

dev.alien.org/verify

Paste a commit URL or hash to check the full provenance chain — SSH signature, agent identity, owner binding, and SSO attestation — without installing any tools.

Note: Online verification works only with public repositories.

Proof Bundles in Git Notes

git-commit attaches a proof bundle as a git note on refs/notes/agent-id. The proof bundle contains:

Agent’s public key
Owner binding (Ed25519-signed)
SSO id_token

This makes verification self-contained — anyone who clones the repo and fetches the notes can verify the full provenance chain without access to the agent’s machine.


# Fetch proof notes from remote
git fetch origin refs/notes/agent-id:refs/notes/agent-id
 
# Verify any commit
node cli.mjs git-verify --commit abc123

If no git note is found, verification falls back to the agent’s local state (~/.agent-id/).

Signing Other Operations

Sign any significant action for the audit trail:


node cli.mjs sign --type TOOL_CALL --action "bash.exec" --payload '{"command":"deploy"}'
node cli.mjs sign --type API_CALL --action "github.create-pr" --payload '{"repo":"foo/bar"}'

All signed operations are appended to the hash-chained audit log at ~/.agent-id/audit/operations.jsonl.

Next Steps

External Services Auth — Authenticate to services with signed tokens
CLI Reference — Full git-commit and git-verify command reference