Git - Sign Commits with SSH

Sign your git commits using an SSH key stored in your Keeper Vault

About

Signing your git commits is important. It verifies authorship, ensures the integrity of committed content, prevents identity spoofing, and establishes non-repudiation. Using a cryptographic signature with your private key demonstrates a commitment to the authenticity and security of your contributions, building trust among collaborators and protecting the repository from potential tampering and malicious code.

This integration allows developers to sign git commits with an SSH key protected in your Keeper Vault (via Keeper Secrets Manager).

Download the latest git-ssh-sign binaries

Features

• Signs git commits using an SSH key stored in Keeper Vault.

• Removes the need for SSH keys on disk for secure DevOps workflows.

• Works on Windows, MacOS, and Linux.

• Source code at https://github.com/Keeper-Security/git-ssh-sign

Prerequisites

In order to utilize this integration, you will need:

• Keeper Secrets Manager access (See the Quick Start Guide for more details)

  • Secrets Manager add-on enabled for your Keeper account

  • Membership in a Role with the Secrets Manager enforcement policy enabled

• A Keeper Secrets Manager Application with SSH key(s) shared to it

  • See the Quick Start Guide for instructions on creating an Application

• An initialized Keeper Secrets Manager Configuration

  • This integration only accepts JSON format configurations

• Git installed with a minimum version of 2.34.0

Setup

1. Secrets Manager Configuration

• Login to the Keeper Web Vault or Desktop App

• Create a shared folder (e.g. "Git SSH Keys")

• Add a SSH Key record to the shared folder

• Generate

In order to fetch the SSH key from your vault, this integration uses the zero-knowledge Keeper Secrets Manager.

It expects to find the Secrets Manager configuration file at .config/keeper/ssh-sign.json in the user's home directory for all systems. If this configuration is not found, it will check ssh-sign.json as a backup. The Secrets Manager application must have access to the shared folder in which your SSH key is stored.

For help in setting up your application and obtaining your configuration file, you can find detailed instructions here.

2. Git Config

After successfully configuring Secrets Manager, you can now configure git to sign your commits automatically. This can be done locally or globally, depending on your needs.

Four pieces of information are required in your config:

1. Tell git you want to sign all commits.

2. Tell git you want to use SSH signing over the default GPG signing.

3. Tell git the location of this integration's executable file. (download here)

4. Tell git the UID of the SSH key to be used to sign.

We can do this for the local Git repository with the following commands (add the --global flag to set these globally):

git config commit.gpgsign true
git config gpg.format ssh
git config gpg.ssh.program <path to this binary>
git config user.signingkey <SSH Key UID>

Your git config will now include these attributes:

[commit]
	gpgsign = true
[gpg]
	format = ssh
[user]
	signingKey = <SSH Key UID>
[gpg "ssh"]
	program = path/to/ssh-sign

3. Add Keys to GitHub / GitLab

3.1 Setup GitHub

For GitHub to verify the signature used to sign the commit, you will need to upload your SSH key's public key to your GitHub account. GitHub will then use this public key to verify the signature and display the verified tag in the UI.

For full details on adding your public key to your account, see GitHub's official documentation.

Important: Be sure to set the type of key to "signing key".

3.2 Setup GitLab

For GitLab to verify the signature used to sign the commit, you will need to upload your SSH key's public key to your GitLab account. GitLab will then use this public key to verify the signature and display the verified tag in the UI.

For full details on adding your public key to your account, see Gitlab's official documentation.

Important: Be sure to set the type of key to "signing key" or "Authentication and signing".

Verify Signatures

Git is now configured to automatically sign all commits, regardless of whether you use the terminal or an IDE interface to interact with git. It also removes the need to use the -S flag for commit signing.

You can confirm your commit has been signed with git show --pretty=raw in the terminal.

GitHub and GitLab

Once you have signed a commit and pushed it to GitHub or GitLab, you should see the verified tag next to your commit in the Git history automatically. No further work is needed.

Local verification

If your repos are stored in your own datacenter, you can verify commits locally on the command line. In order to so this, you will need to create an allowed_signers file which is a record of authorized signing keys.

Typically, this file is saved either globally at .ssh/allowed_signers or in the local repo at .git/allowed_signers. The path to this file needs then to be added to your .gitconfig or .git/config file.

git config gpg.ssh.allowedSignersFile path/to/file

Each line of your allowed_signers file should be a principal of an authorized signing key. The line should start with the email address associated with the public key, separated by a space. For example:

[e-mail] ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEQvSrBv28KLAjYO7pD91prhlenrm3hZ4B7DdcB/4/H+

The format of the allowed signers file is documented in full here.

While it is correct syntax to have more than one email address associate with a single public key, it is not recommended or currently supported.

To verify your git history use:

# Verify all commits in the repo
git log --show-signature

# Verify the last commit in the repo
git log --show-signature -1

Source

The source code for this integration is open source and available on GitHub. Issues can be submitted here.