Signing Git commits and tags binds each change to a key or identity the author controls, so that reviewers, forges and build systems can tell a real commit from one that merely claims a name and email address. This guide is a practical how-to: choosing between OpenPGP (GPG), SSH and Sigstore gitsign keyless signing, configuring each, verifying signatures locally and in CI, enforcing signing on GitHub with rulesets and vigilant mode, and handling bots, key rotation and revocation.
For the wider repository integrity picture, including protected branches, history rewrites and gittuf, see our Git Repository Security Guide. This page focuses on the mechanics of signing.
Key takeaways
- Git author and committer fields are free text. Without a signature, anyone with push access can attribute a commit to anyone else.
- Git supports three signature formats through
gpg.format:openpgp(the default),x509andssh. Gitsign uses the x509 path with short-lived Sigstore certificates. - SSH signing is the simplest to roll out for most teams: it needs Git 2.34 or later on GitHub, reuses familiar keys and works with hardware security keys.
- A signature only matters if something checks it. Configure an allowed signers file or keyring for local verification, verify in CI, and require signed commits on protected branches.
- Bots and automation are non-human identities that sign too. Give each one its own key or use platform signing, keep keys out of long-lived secrets where you can, and track them in your NHI inventory.
Why sign commits and tags
Every Git commit records an author and a committer, each a name and email address set by local configuration. Git does not check them. A forge such as GitHub links a commit to an account by matching the email address, which means a commit pushed by one account can display another person's avatar and name. Signing closes that gap in three ways:
- Attribution. A verified signature shows that whoever made the commit held a key registered to that identity.
- Tamper evidence for releases. A signed annotated tag lets consumers check that the release point was created by a maintainer, which matters because tags can be moved or recreated.
- Policy input. Branch rules, build pipelines and provenance systems can refuse unsigned or unverified changes, which raises the cost of pushing malicious code with a stolen token alone.
Be clear about what signing does not do. It does not prove the code is safe, and it does not stop a compromised developer laptop from signing malicious commits if the key is available without user presence. It is one control in a set that includes review, branch protection and build provenance. It maps to NIST SP 800-53 controls CM-14 Signed Components and SI-7 Software, Firmware, and Information Integrity, and supports the source integrity expectations in the SSDF.
Choosing a signing method
The three options differ in key management, verification and how forges display them.
| Aspect | OpenPGP (GPG) | SSH | Gitsign (Sigstore keyless) |
|---|---|---|---|
| Git setting | gpg.format=openpgp (default) | gpg.format=ssh | gpg.format=x509 with gpg.x509.program=gitsign |
| Key lifetime | Long-lived, with optional expiry | Long-lived; validity windows in allowed signers file | Ephemeral certificate, about 10 minutes in the project's example |
| Identity source | Key and user IDs you create | Key you create; principals in allowed signers file | Your OIDC identity, for example a GitHub or Google account |
| Verification | Keyring and trust level | Allowed signers file | gitsign verify against identity, issuer and Rekor |
| GitHub badge | Verified when public key is on the account | Verified when signing key is on the account (Git 2.34+) | Shown as Unverified (see below) |
| Public record | None | None | Entry in the Rekor transparency log, public by default |
GitHub also supports S/MIME using an X.509 key issued by your organisation, which requires Git 2.19 or later and does not need the public key uploaded to GitHub. This suits organisations that already run an internal PKI with smart cards.
A sensible default for most engineering teams is SSH signing with a hardware-backed key, plus gitsign for teams that want keyless signing and can verify with Sigstore tooling rather than the forge badge. Our Keyless vs Key-Based Code Signing page discusses the trade-off at artefact level.
Setting up SSH signing
- Create or choose a key. Prefer a dedicated signing key, ideally on a FIDO2 security key (
ed25519-sk) so that each signature needs a touch. GitHub allows an authentication key to be reused as a signing key and has no limit on the number of signing keys, but a separate signing key makes rotation and revocation cleaner. - Configure Git. Set the format and key:
git config --global gpg.format sshgit config --global user.signingkey ~/.ssh/id_ed25519_sk.pubgit config --global commit.gpgsign truegit config --global tag.gpgsign true
- Register the key with the forge. On GitHub, add it as a signing key (not only an authentication key) in your account settings.
- Configure local verification. Create an allowed signers file listing each trusted principal (email) and public key, and point
gpg.ssh.allowedSignersFileat it. Git treats keys in this file as fully trusted. - Test. Make a commit and run
git log --show-signature -1orgit verify-commit HEAD.
The Git documentation describes two further settings that matter for operations. gpg.ssh.defaultKeyCommand runs when user.signingkey is not set and prints a key prefixed with key::, which is useful with SSH agents that hold several keys. gpg.ssh.revocationFile holds an SSH key revocation list or revoked public keys; any key found there is always treated as trust level "never" and its signatures show as invalid.
Since OpenSSH 8.8, entries in the allowed signers file can carry valid-after and valid-before options to set a key lifetime, and Git treats a signature as valid if the key was valid when the signature was created. Keep in mind that the creation time Git uses comes from the commit itself, which the signer controls, so validity windows help with orderly rotation but are not a defence against a stolen key. Revocation is.
Setting up OpenPGP (GPG) signing
- Generate a key with a modern algorithm (Ed25519 or RSA 4096) and an expiry of one to two years. Keep the primary key offline and use a signing subkey, or store the key on a smart card or security key.
- Configure Git:
git config --global user.signingkey <KEYID>, then enablecommit.gpgsignandtag.gpgsign. Leavegpg.formatat its default ofopenpgp. - Publish the public key to the forge account. The user ID email on the key must match a verified email on the account for GitHub to mark commits Verified.
- Set a trust policy for verification.
gpg.minTrustLevelsets the minimum trust level for all verification operations. Without it, Git requires at least marginal trust for merges and at least undefined for other operations, which is permissive. Set it explicitly in CI and on release machines. - Plan expiry. Extend or rotate before the expiry date and republish the updated public key, or new signatures will fail verification.
OpenPGP remains common in open-source release signing and Linux packaging, but its web-of-trust model is harder to operate inside a company than an allowed signers file or a corporate PKI.
Setting up gitsign keyless signing
Gitsign signs commits and tags with your OpenID Connect identity instead of a long-lived key, using Sigstore's Fulcio certificate authority and Rekor transparency log. Our Sigstore Guide covers those components in detail.
- Install gitsign from a package manager or with the Go toolchain.
- Configure Git, per repository or globally: set
gpg.x509.programtogitsignandgpg.formattox509, and optionally enablecommit.gpgsignandtag.gpgsign. - Sign. A signed commit or tag opens a browser to complete the Sigstore login. Gitsign stores no refresh tokens or key material on disk; the optional
gitsign-credential-cachekeeps credentials in memory so that you typically authenticate about once every 10 minutes. - Verify with
gitsign verify, passing the expected--certificate-identityand--certificate-oidc-issuer. The project states this is preferred overgit verify-commitandgit verify-tag, because those commands do not check who signed the data.
Three points need planning before a wide rollout:
- Verification relies on Rekor. The certificates expire within minutes, so ordinary X.509 checks would reject them; Rekor proves the certificate was valid when the signature was made.
- Privacy. The signature and certificate become part of the repository, and by default entries go to the public Rekor instance. Certificates can include email addresses and repository details. For private work, consider a private Sigstore deployment or accept and document the exposure.
- Forge display. GitHub shows gitsign commits as Unverified, because the Sigstore CA is not in GitHub's trust root and the short-lived certificates have expired. Do not combine gitsign with a GitHub rule that requires verified signatures unless you have tested the interaction; verify in CI with gitsign instead.
Verifying signatures locally and in CI
Signing without verification is decoration. Build verification into three places:
- Developer workstations. Distribute a shared allowed signers file or keyring from a trusted location (for example a protected repository), and set
log.showSignaturefor reviewers who want signatures in every log view. - Merge and release pipelines. Add a CI step that verifies every commit in a pull request range, and every release tag, against the organisation's allowed signers file, keyring or gitsign identity policy. Fail the job on unsigned, unknown or revoked signatures.
- Consumers of your releases. Publish how to verify your tags: which keys or identities sign them and where the public material lives.
Keep the allowed signers file under change control with code owners, because whoever can edit it decides which keys are trusted. Treat additions with the same care as adding an administrator.
Enforcing signing on GitHub
According to GitHub's commit signature verification documentation, GitHub supports GPG, SSH and S/MIME signatures on commits and tags, and administrators can require signed and verified commits on protected branches.
Require signed commits
The Require signed commits ruleset rule allows contributors and bots to push only commits that are signed and verified. Points to test before enforcing:
- When a branch is created, only commits not reachable from other branches are checked; when it is updated, all commits in the pushed range are checked.
- Unsigned commits on a pull request's head branch can block a squash merge, even though GitHub would sign the final squash commit. Fix by rewriting and signing the head branch, or by a merge from someone with bypass permission.
- With rebase and merge, GitHub adds commits without signature verification because it cannot sign them on the user's behalf; its suggested workaround is to rebase locally and push.
- Bypass permissions can be granted to roles, teams or GitHub Apps. Keep that list short and review it, because a bypass actor is an unsigned path into the branch.
Vigilant mode
Vigilant mode is off by default. When a user enables it, GitHub marks unsigned commits attributed to that user as Unverified, which makes impersonation visible. A signed and verified commit shows as Partially verified when an author who is not the committer has vigilant mode on. Encourage all staff to enable it, especially maintainers whose names would be attractive to impersonate.
Persistent verification
GitHub stores a verification record with a timestamp when a signed commit is pushed, exposed as a verified_at field in the REST API. Records persist even if keys are later rotated, revoked or expired, or the contributor leaves, and GitHub does not re-verify old commits when keys change. This keeps history readable after rotation, but it also means revoking a stolen key on GitHub does not flag commits already pushed with it. Your own revocation file and CI verification are what catch those.
Bots, automation and web commits
Automation creates a large share of commits in many repositories: dependency update bots, release tooling, code generators and AI coding agents. Each is a non-human identity and needs a signing approach.
- Web UI commits made on GitHub are signed by GitHub with its own GPG key and show as Verified.
- GitHub Apps and bots get verified commits when they authenticate as the app or bot and do not supply custom author, committer or signature information, for example when using the Commits API. This is usually the best option: no signing key to manage. Our GitHub App Private Key Security Guide covers protecting the app's own credential.
- CI jobs that commit (version bumps, changelog updates) can use gitsign with the workload's OIDC token, so there is no long-lived key in the pipeline. Verify the expected workflow identity in policy.
- Bots that must hold a key should have a dedicated key per bot, stored in a secrets manager or KMS-backed signer, never shared between bots or with a human, with an owner, a rotation date and an entry in the allowed signers file that names the bot.
- AI coding agents acting for a developer should not sign with that developer's personal key. Give the agent its own identity and commit through a pull request, so humans review and sign the merge.
Rotation, revocation and offboarding
- Rotation. Set an expiry on GPG keys and a validity window on SSH allowed signers entries. Rotate signing keys on a fixed schedule and whenever a laptop or security key is replaced.
- Suspected compromise. Remove the key from the forge account, add it to
gpg.ssh.revocationFileor publish a GPG revocation certificate, and update the allowed signers file. Then review commits and tags signed with that key since the suspected exposure, because forge verification records will still show them as verified. - Offboarding. Close the leaver's signing keys in the allowed signers file with a
valid-beforedate rather than deleting them, so historical commits still verify while new ones do not. - Evidence. Keep a record of which keys and identities were trusted for which period. Auditors and incident responders will ask.
Common failure patterns
- Signing without verifying. Developers sign, but no pipeline checks signatures, so a commit signed by an unknown key passes as easily as an unsigned one.
- Trusting the badge alone. The forge badge says a key is attached to an account, not that the account is on your trusted list for this repository.
- Shared bot keys. One signing key used by several automation jobs and stored as a long-lived CI secret, so a leak from any job lets attackers sign as all of them.
- Keys without user presence. Software keys with no passphrase on developer laptops mean malware can sign silently.
- Unreviewed bypass lists. Required signing is enabled, but several teams and apps hold bypass permission and use it routinely.
- Gitsign plus required verified signatures on GitHub without testing, which blocks merges or pushes teams into bypass.
- Unsigned release tags. Commits are signed but release tags are lightweight and unsigned, leaving the most consumed reference unprotected.
Practitioner checklist
- Choose a default method (SSH with hardware-backed keys, S/MIME with corporate PKI, or gitsign) and document it.
- Enable
commit.gpgsignandtag.gpgsignin managed developer configuration. - Publish an allowed signers file or keyring under code owner review, with validity windows and a revocation file.
- Verify every commit and release tag in CI, failing on unsigned, unknown or revoked signatures.
- Enable Require signed commits on protected branches, test squash and rebase flows first, and minimise bypass actors.
- Ask staff, and require maintainers, to turn on vigilant mode.
- Give every bot and agent its own signing identity, preferring platform signing or keyless OIDC, and record it in the NHI inventory.
- Rotate keys on a schedule, and have a revocation and commit review procedure ready for compromise.
- Sign release tags and publish verification instructions for consumers.
Standards and references
- GitHub Docs: About commit signature verification
- GitHub Docs: Available rules for rulesets
- Git: gpg configuration reference
- Sigstore: gitsign
- NIST: SP 800-218 Secure Software Development Framework (SSDF) Version 1.1
- OpenSSF: SLSA v1.0 Security Levels
- NIST: SP 800-53 Rev. 5 (CM-14 Signed Components, SI-7 Software, Firmware, and Information Integrity)
- MITRE ATT&CK: Compromise Software Supply Chain
Related NHI Mgmt Group resources: Git Repository Security Guide · Sigstore Guide · Keyless vs Key-Based Code Signing · Code Signing Security Guide