|$ curl https://forge-ai.dev/api/markdown?path=docs/git/signing

$cat docs/git-signing.md

updated Today·22-30 min read·published

Git Signing

◆Git◆Signing◆Security◆Intermediate🎯Free Tools

Introduction

Signed commits and tags prove authorship cryptographically. Hosts like GitHub show a Verified badge when the signing key matches your account.

SSH Commit Signing (Recommended)

SSH signing is simpler than GPG for many developers — reuse your auth key or a dedicated signing key.

ssh-sign.sh

Bash

1	# Generate a dedicated signing key (optional)
2	ssh-keygen -t ed25519 -f ~/.ssh/git_signing -C "git-signing"
3
4	git config --global gpg.format ssh
5	git config --global user.signingkey ~/.ssh/git_signing.pub
6	git config --global commit.gpgsign true
7	git config --global tag.gpgsign true
8
9	# Allowed signers file (local verify)
10	mkdir -p ~/.config/git
11	echo "$(git config user.email) namespaces="git" $(cat ~/.ssh/git_signing.pub)" \
12	> ~/.config/git/allowed_signers
13	git config --global gpg.ssh.allowedSignersFile ~/.config/git/allowed_signers
14
15	git commit -S -m "feat: signed commit"
16	git log --show-signature -1

✓

best practice

Add the same public key in GitHub Settings → SSH and GPG keys → Signing keys.

GPG Signing

gpg-sign.sh

Bash

1	gpg --full-generate-key
2	gpg --list-secret-keys --keyid-format=long
3	# signing key id example: RSA 4096/ABCD1234
4
5	git config --global user.signingkey ABCD1234
6	git config --global commit.gpgsign true
7	git config --global gpg.program gpg
8
9	gpg --armor --export ABCD1234
10	# paste into GitHub GPG keys
11
12	git commit -S -m "feat: gpg signed"
13	git tag -s v1.0.0 -m "Release 1.0.0"

Verification

verify.sh

Bash

1	git verify-commit HEAD
2	git verify-tag v1.0.0
3	git log --show-signature -5
4	git show --show-signature HEAD

Result	Meaning
Good signature	Key trusted / allowed
Untrusted	Signature OK but trust not established
No signature	Commit not signed
Bad signature	Tampered or wrong key

GitHub Verified Badges

Upload SSH signing key or GPG public key to GitHub
Email on commits must match a verified GitHub email (or use noreply)
Protected branches can require signed commits
Web commits from GitHub UI are signed by GitHub

github-noreply.sh

Bash

1	git config --global user.email "ID+username@users.noreply.github.com"

Per-Repo or Per-Command

selective.sh

Bash

1	# Disable globally; enable per repo
2	git config --global commit.gpgsign false
3	git config commit.gpgsign true # local
4
5	# One-off
6	git commit -S -m "feat: must sign"
7	git commit --no-gpg-sign -m "wip: local only"

Troubleshooting

GPG: pinentry / TTY issues — export GPG_TTY=$(tty)
SSH: ensure gpg.format ssh and signingkey points at .pub
GitHub: email mismatch removes Verified
Rebase/amend requires re-sign: git rebase --exec 'git commit --amend --no-edit -S'

gpg-tty.sh

Bash

1	echo 'export GPG_TTY=$(tty)' >> ~/.bashrc
2	export GPG_TTY=$(tty)
3	echo "test" \| gpg --clearsign

FAQ

Common questions and short answers.

SSH or GPG?

SSH is usually easier; GPG has broader historic tooling.

Must every commit be signed?

Only if team policy / protected branch requires it.

Do merges need signing?

Merge commits created locally follow commit.gpgsign.

Signing Setup Checklist

Key generated and backed up
user.signingkey configured
commit.gpgsign enabled (global or local)
Public key uploaded to GitHub/GitLab
Commit email matches host account
verify-commit succeeds locally

checklist.sh

Bash

1	echo "[ ] Key generated and backed up"
2	echo "[ ] user.signingkey configured"
3	echo "[ ] commit.gpgsign enabled (global or local)"
4	echo "[ ] Public key uploaded to GitHub/GitLab"
5	echo "[ ] Commit email matches host account"
6	echo "[ ] verify-commit succeeds locally"

Notes for AI Agents

Prefer SSH signing setup for new users
Never paste private keys into chat logs
Re-sign after rebase when policy requires
Check email matches host verified emails

🔥

pro tip

See How to Master Git for curriculum order.

Worked Examples

These end-to-end examples reinforce the signing concepts above. Run them in a disposable lab under /tmp so mistakes are cheap.

Example A — happy path

example-a.sh

Bash

1	# Lab for signing
2	rm -rf /tmp/git-lab-signing && mkdir -p /tmp/git-lab-signing
3	cd /tmp/git-lab-signing
4	git init -b main
5	git config user.email "lab@example.com"
6	git config user.name "Lab User"
7	echo "# lab" > README.md
8	git add README.md
9	git commit -m "chore: init lab for signing"
10	git status -sb
11	git log --oneline --decorate

Example B — recover from a mistake

example-b.sh

Bash

1	# Make a bad commit, then recover safely
2	echo bad > oops.txt
3	git add oops.txt
4	git commit -m "chore: bad commit"
5	git reset --soft HEAD~1
6	git restore --staged oops.txt
7	rm oops.txt
8	git status -sb
9	# If you had hard-reset already:
10	# git reflog \| head
11	# git reset --hard HEAD@{1}

🔥

pro tip

Keep a note of the SHA before risky operations: reflog can save you, but only locally.

Troubleshooting

Symptoms you will hit in real repos, and the first commands to run.

Unexpected dirty tree

trouble-dirty.sh

Bash

1	git status -sb
2	git diff
3	git diff --staged
4	git stash list
5	# Discard one file:
6	git restore path/to/file
7	# Unstage one file:
8	git restore --staged path/to/file

Diverged from remote

trouble-diverge.sh

Bash

1	git fetch origin
2	git status -sb
3	git log --oneline --left-right HEAD...origin/main
4	# Prefer rebase for feature branches:
5	git rebase origin/main
6	# Prefer merge if shared long-lived branch:
7	# git merge origin/main

Conflict markers left behind

trouble-markers.sh

Bash

1	git diff --check
2	rg -n '^(<<<<<<<\|=======\|>>>>>>>)' \|\| true
3	# Fix files, then:
4	git add -A
5	git status

danger

Never force-push to main to "fix" divergence. Use revert or a forward fix.

Command Cheatsheet

Keep this short list nearby while practicing signing.

cheatsheet.sh

Bash

1	git status -sb
2	git log --oneline --graph --decorate -15
3	git diff
4	git diff --staged
5	git add -p
6	git commit -m "type(scope): summary"
7	git switch -c feature/x
8	git fetch origin --prune
9	git rebase origin/main
10	git push -u origin HEAD
11	git restore --staged PATH
12	git restore PATH
13	git stash push -u -m "wip"
14	git reflog \| head
15	git rev-parse HEAD
16	git remote -v

Read the full curriculum order in How to Master Git
Look up flags in Commands Reference
Follow the staged path in Git Roadmap

Team Policy Notes

Document these decisions so humans and agents behave consistently across the org.

Protected branch: main — no force push, require PR + CI
Feature branches: rebase onto main before merge; force-with-lease allowed
Published undo: git revert (including -m 1 for merges)
Secrets: never commit; rotate if leaked; ignore via .gitignore
Commit style: Conventional Commits
Signing: required if compliance asks; SSH signing preferred

policy.md

Markdown

1	# Git policy (excerpt)
2	- defaultBranch: main
3	- updateStrategy: rebase
4	- mergeStrategy: squash (via host)
5	- allowForcePush: feature/* only with --force-with-lease
6	- requireSignedCommits: true
7	- maxPRLines: 400 (soft)

✓

best practice

Automate policy with hooks + CI — see Hooks and Best Practices.

Agent Verification Prompts

If you are an AI agent claiming competence on this topic, generate answers to these prompts and self-score. Fail closed on any critical miss.

Produce a safe command sequence for the primary workflow on this page
Name one destructive anti-pattern and the safer alternative
Show how to recover if the operation goes wrong (reflog/revert/abort)
List files/paths that must never be committed
State whether force-push is allowed in the scenario — default no on main

agent-fetch.sh

Bash

1	curl -s "https://forgelearn.dev/api/markdown?path=git/mastery" \| head
2	curl -s "https://forgelearn.dev/api/agent?skill=forgelearn-git" \| head
3	curl -s https://forgelearn.dev/skills/forgelearn-git/SKILL.md \| head

danger

Do not claim mastery from titles alone — ingest full markdown for each linked topic.

Community

Get help on Slack, Discord or VIP

Stuck on a guide? Join the community and ask.

Join Slack Join Discord Kaundal VIP

X GitHub YouTube Instagram Facebook Discord Slack Telegram Buy me a coffee Ko-fi Sponsor