What is commit signing?
Signing a commit allows you to verify the origin of that commit, giving you confidence that the author made the commit through Gearset. Many VCS providers will show a Verified badge next to signed commits.
If a commit isn’t signed, there is no way to verify who made the commit, or where the commit came from.
You’ll need a Deployment Teams license to set up and use commit signing.
Gearset signs commits using a unique GPG key pair for each user. Every GPG key pair has a private key and a public key. The commit is signed with the private key, and is verified with the public key.
How to set up commit signing
There are two steps to setting up commit signing:
A team owner generates the GPG key pairs in Gearset
Each team member adds their GPG public key to the VCS
Generating the GPG key pairs in Gearset
Note: A team owner needs to complete this step.
On the Team security settings, go to the "Commit signing" section where you can download a CSV containing your team members' public keys. Gearset will generate a unique GPG key pair for each team member.
Gearset signs each team member’s commit with their unique private key. These private keys remain stored securely within Gearset. Public keys are used to verify that a commit was signed with a specific team member’s private key.
The CSV contains each team members’ email and their public key. Public keys are used for verification, not for signing commits, so it’s okay for team members to know each other’s public key.
Distribute the public key to each team member, so that they can add their public key to the VCS.
Adding a public key to the VCS
Note: Each team member needs to complete this step.
Some VCS providers allow you to upload your public key, so that the VCS can verify your commits. You can upload your public key to:
You don’t need to complete this step for other VCS providers. Commits pushed to other VCS providers will be signed with the private key, but won’t show the Verified badge.
When you add a new GPG key to your VCS, you must include the BEGIN and END markers:
----BEGIN PGP PUBLIC KEY BLOCK-----
----END PGP PUBLIC KEY BLOCK-----
What do signed commits look like?
Once you’ve generated the GPG key pairs, Gearset will sign each team member’s commit with their unique private key.
Commits will appear with a Verified badge if the team member has added their public key to the VCS.
Commits will appear with an Unverified badge if the team member has not added their public key to the VCS. These commits are signed, but the VCS doesn’t know about the public key so can’t verify the author.
Require signed commits in your VCS
Some VCS providers allow you to set push rules or branch protection rules that require any commit to that branch to be signed.
If you’ve set up a rule that requires signed commits, you won’t be able to commit to the branch until you set up commit signing in Gearset.
Configuring Commit Signing for Team-shared Jobs
When running team-shared jobs, you can configure a specific username and email to sign commits made by these jobs.
You can do this by going to My Account > Team Security and going to the Commit Signing section.
After saving, you can add the key to the VCS.
Questions
Do team members’ keys change if I click the signed commits button again?
No, team member’s keys will remain the same. The team members won’t need to make any changes to their GPG keys in the VCS.
What happens if someone joins my Gearset team?
When a new team member joins, a team owner will need to set up commit signing again.
Follow the process outlined above, and the CSV will include a public key for the new team member. The new team member’s commits in Gearset will now be signed, and will be marked as verified once they’ve added their public key to the VCS.
Existing team members won't need to make any changes to their GPG keys in the VCS.