# Verify a signed change on GitHub

[Read this guide on KeySigner](https://keysigner.io/integrations/guides/verify-a-github-commit/)

Approve a test commit on your phone, then check that GitHub marks the same commit as verified.

## Before you start

**Computer tools and KeySigner on iPhone**

- Pair the KeySigner computer tools with the phone and add the public key to GitHub as a signing key. Use a test repository to check the signature in Git and on GitHub.

## Data and access

- **Shared or checked**. KeySigner signs the test commit. GitHub receives the signed commit when you push and checks the signature against its record of the signing key.
- **Check separately**. Repository push access, branch rules, and unsigned older commits each need their own check.

## 1. Prepare a test repository

Clone a private GitHub test repository that already has a commit. On a test computer or separate user profile, pair the KeySigner desktop tools with your iPhone. Set Git’s user.email to an address verified on your test GitHub account, then preview the global signing settings.

~~~
keysigner-agent setup-git
~~~

**Check.** The preview shows the current and proposed global settings and the intended test public key.

## 2. Register the signing key

Copy the full public key shown for user.signingkey after the key:: prefix. Add it to your GitHub account settings with the key type set to Signing Key. After reviewing the preview, apply the setup.

~~~
keysigner-agent setup-git --apply
~~~

**Check.** GitHub lists the test public key as a signing key. The applied settings match the preview.

## 3. Approve an empty test commit

Run the command from the test repository. It creates a commit without including staged changes. In KeySigner on your iPhone, compare the commit message, author and signing key with what you expect before approving.

~~~
git commit --only --allow-empty -S \
  -m "feat: signed on my phone"
~~~

![KeySigner shows the commit author, message and Approved and signed status.](https://keysigner.io/integrations/guides/verify-a-github-commit/keysigner-commit-approval.png)

Example approval in the KeySigner iPhone simulator.

**Check.** KeySigner shows Approved and signed for the test message. Git reports that the commit was created.

## 4. Verify the signature in Git

With the test commit still at the tip of your branch, verify its signature and record the ID printed on the final line.

~~~
git verify-commit HEAD &&
  git rev-parse HEAD
~~~

**Check.** Git reports a valid signature and prints the full commit ID.

## 5. Check GitHub’s Verified badge

Confirm your remote points to the private test repository and push the test branch. Open the commit on GitHub and select its Verified badge to view the signing details.

**Check.** Match the full commit ID to the one you recorded in Git and compare the key shown in the verification details with the key you registered.

## Check your result

When you finish the test, run keysigner-agent rollback git to restore the global settings saved before setup. Remove only the test signing key from GitHub. The Verified badge records an earlier check. GitHub retains that record in the same repository and its forks after you remove the key.

[How to verify your setup](https://keysigner.io/integrations/verify-a-setup/)

## If you get stuck

### GitHub shows the commit as unverified

Check that you opened the same commit that passed local verification. Compare the public key in the setup preview with the signing key registered in GitHub, then check that the commit’s committer email is verified on that account.

## Tools in this guide

- [GitHub](https://keysigner.io/integrations/github/)
  - [Troubleshoot a commit signature](https://docs.github.com/en/authentication/troubleshooting-commit-signature-verification)
  - [Set up authenticator codes for GitHub](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-totp-app)
  - [Setup requirements](https://keysigner.io/integrations/setup-requirements/#github)

## Setup instructions

- [Manage signing keys in GitHub](https://github.com/settings/keys)
- [Check the verification badge and signing details](https://docs.github.com/en/authentication/troubleshooting-commit-signature-verification/checking-your-commit-and-tag-signature-verification-status)
- [How GitHub keeps verification records](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification#persistent-commit-signature-verification)

[More guides for this task](https://keysigner.io/integrations/tasks/review-code-and-releases/)
