Join our Newsletter — 33% off our NHI Course
Home› Guides› Git Commit and Tag Signing Guide: Set Up…
Guide Software & AI Supply Chain

Git Commit and Tag Signing Guide: Set Up GPG, SSH and Gitsign and Enforce Verification

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 18 November 2026 14 min read
On this page

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), x509 and ssh. 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.

AspectOpenPGP (GPG)SSHGitsign (Sigstore keyless)
Git settinggpg.format=openpgp (default)gpg.format=sshgpg.format=x509 with gpg.x509.program=gitsign
Key lifetimeLong-lived, with optional expiryLong-lived; validity windows in allowed signers fileEphemeral certificate, about 10 minutes in the project's example
Identity sourceKey and user IDs you createKey you create; principals in allowed signers fileYour OIDC identity, for example a GitHub or Google account
VerificationKeyring and trust levelAllowed signers filegitsign verify against identity, issuer and Rekor
GitHub badgeVerified when public key is on the accountVerified when signing key is on the account (Git 2.34+)Shown as Unverified (see below)
Public recordNoneNoneEntry 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

  1. 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.
  2. Configure Git. Set the format and key:
    • git config --global gpg.format ssh
    • git config --global user.signingkey ~/.ssh/id_ed25519_sk.pub
    • git config --global commit.gpgsign true
    • git config --global tag.gpgsign true
  3. Register the key with the forge. On GitHub, add it as a signing key (not only an authentication key) in your account settings.
  4. Configure local verification. Create an allowed signers file listing each trusted principal (email) and public key, and point gpg.ssh.allowedSignersFile at it. Git treats keys in this file as fully trusted.
  5. Test. Make a commit and run git log --show-signature -1 or git 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

  1. 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.
  2. Configure Git: git config --global user.signingkey <KEYID>, then enable commit.gpgsign and tag.gpgsign. Leave gpg.format at its default of openpgp.
  3. 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.
  4. Set a trust policy for verification. gpg.minTrustLevel sets 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.
  5. 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.

  1. Install gitsign from a package manager or with the Go toolchain.
  2. Configure Git, per repository or globally: set gpg.x509.program to gitsign and gpg.format to x509, and optionally enable commit.gpgsign and tag.gpgsign.
  3. 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-cache keeps credentials in memory so that you typically authenticate about once every 10 minutes.
  4. Verify with gitsign verify, passing the expected --certificate-identity and --certificate-oidc-issuer. The project states this is preferred over git verify-commit and git 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.showSignature for 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.revocationFile or 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-before date 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.gpgsign and tag.gpgsign in 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

Related NHI Mgmt Group resources: Git Repository Security Guide · Sigstore Guide · Keyless vs Key-Based Code Signing · Code Signing Security Guide

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 18 November 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org