Github Commit Signing

Github Commit Signing

Git commit signing provides a way to cryptographically associate a commit with a signing key.

Without commit signing, a Git commit contains an author name and email address, but those fields alone do not prove that the person shown as the author actually created the commit. Signed commits add an additional verification layer.

GitHub can verify a cryptographic signature against a signing key registered with the user’s GitHub account and display successfully verified commits with the Verified status.

This guide shows how to configure Git to sign commits using a dedicated SSH key.

How SSH Commit Signing Works

An SSH key pair contains two parts:

  • Private key – remains on your system and is used to create the signature.
  • Public key – added to GitHub so that GitHub can verify signatures created by the corresponding private key.

The private key should never be uploaded to GitHub or shared with another person.

Although an existing SSH authentication key can also be used for signing, using a dedicated signing key makes the purpose of the key clearer and keeps authentication and signing functions separate.

Requirement: SSH commit signing requires Git 2.34 or later.

You can check the installed version with:

git --version

Step 1: Generate a Signing Key

Open a terminal and create a new Ed25519 SSH key:

ssh-keygen -t ed25519 -C "[email protected]"

The email comment is mainly there to make the key easier to identify. Using the same email address associated with your GitHub account is a convenient choice.

If the system does not support Ed25519, an RSA key can be generated instead:

ssh-keygen -t rsa -b 4096 -C "[email protected]"

During key creation, ssh-keygen will ask where the key should be stored.

If you already have SSH keys on the system, be careful not to overwrite an existing key. In that case, give the signing key a separate name, for example:

~/.ssh/id_ed25519_signing

This makes it easier to distinguish a commit-signing key from keys used for SSH authentication.

The generated files will normally include:

id_ed25519_signing
id_ed25519_signing.pub

The file ending in .pub is the public key. The file without .pub is the private key.

Do not publish or upload the private key.

Step 2: Copy the Public Key

Open the .pub file and copy its full contents.

On macOS, for example:

cat ~/.ssh/id_ed25519_signing.pub | pbcopy

You can also display it directly:

cat ~/.ssh/id_ed25519_signing.pub

The public key will look similar to:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... [email protected]

Copy the complete line.

Step 3: Add the Signing Key to GitHub

Open GitHub and go to:

Settings → SSH and GPG keys → New SSH key

You can open the settings page directly here:


https://github.com/settings/keys

When adding the key:

  1. Enter a descriptive title, such as Laptop Commit Signing.
  2. Select Signing Key as the key type.
  3. Paste the complete public key.
  4. Save the key.

The public key registered in GitHub will now be available for signature verification.

Step 4: Configure Your Git Identity

Make sure Git is configured with the name and email address you want associated with your commits.

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

You can review the configured values with:

git config --global user.name
git config --global user.email

Step 5: Tell Git to Use SSH for Signing

Git supports different signing formats. Configure it to use SSH signatures:

git config --global gpg.format ssh

Step 6: Configure the Signing Key

Point Git to the public part of the SSH signing key.

For example:

git config --global user.signingkey ~/.ssh/id_ed25519_signing.pub

If the key is stored somewhere else, replace the path with the actual location of the .pub file.

Step 7: Sign Commits Automatically

You can tell Git to sign all commits by default:

git config --global commit.gpgsign true

Your complete configuration now consists of:

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519_signing.pub
git config --global commit.gpgsign true

Step 8: Create a Test Commit

Create or modify a file inside a Git repository and make a normal commit:

git add .
git commit -m "Test signed commit"

Because automatic signing has been enabled, Git should sign the commit using the configured SSH key.

You can inspect the commit locally with:

git log --show-signature -1

Push the commit to GitHub:

git push

Open the repository’s commit history. If GitHub can successfully verify the signature against the signing key registered with your account, the commit should appear with a Verified badge.

Signing Only Selected Commits

Automatic signing is convenient, but it is not mandatory.

If commit.gpgsign is not enabled globally, an individual commit can be signed using:

git commit -S -m "Signed commit"

This can be useful when only certain repositories or workflows require signed commits.

Repository-Level Configuration

The examples above use --global, which applies the configuration to all repositories for the current user.

If signing should only be enabled for one repository, run the configuration commands inside that repository without --global.

For example:

git config gpg.format ssh
git config user.signingkey ~/.ssh/id_ed25519_signing.pub
git config commit.gpgsign true

This provides more flexibility when different projects require different signing identities or keys.

Common Problems

Git Is Too Old

SSH signatures require Git 2.34 or later.

Check your version:

git --version

If the installed version is older, update Git before configuring SSH commit signing.

The Commit Is Signed but GitHub Does Not Show “Verified”

Check that:

  • The correct public key was added to GitHub.
  • The key was added as a signing key.
  • Git is using the expected signing key.
  • The configured Git identity corresponds to the GitHub account you expect.

You can check the configured key with:

git config --global user.signingkey

The Wrong SSH Key Is Being Used

If several SSH keys exist on the workstation, explicitly configure the signing key rather than relying on an automatically selected key:

git config --global user.signingkey ~/.ssh/id_ed25519_signing.pub

An Existing SSH Key Was Overwritten

When generating a new key, always check the proposed filename before confirming it.

Using a dedicated name such as:

id_ed25519_signing

reduces the risk of overwriting an existing authentication key such as id_ed25519.

Security Considerations

A verified commit only provides useful assurance if the associated private signing key remains protected.

Keep the following points in mind:

  • Never commit the private key to a repository.
  • Never upload the private key to GitHub.
  • Do not send private keys through chat or email.
  • Use separate signing keys where separation from SSH authentication is desirable.
  • Remove old signing keys from GitHub when the corresponding device or key is no longer trusted.

If a signing key is lost or suspected to be compromised, remove its public key from GitHub and replace it with a new signing key.

Why Commit Signing Matters

Commit signing does not replace repository permissions, branch protection, code review or CI/CD security.

It solves a more specific problem: verifying that a commit was signed using a cryptographic key associated with a known GitHub account.

This becomes particularly useful in environments where understanding who produced a change matters for software supply-chain security, privileged repositories or controlled deployment workflows.

Useful References

Once configured, SSH signing requires very little additional work during normal development. Commits can be signed automatically, while GitHub provides a visible verification status in the repository history.

Comments are closed.