AdvancedLesson 26 of 307 min read

Security: Signed Commits, Keys, Tokens and Scanning

See why names on commits prove nothing, sign commits for real with GPG, and build habits for keys, tokens, secrets and updates.

In this lesson you will

  • Explain what a signed commit proves
  • Read signature verdict letters
  • Protect keys and token files
  • Review tokens against a simple policy

About 34 minutes

Anyone can type your name

Git believes whatever name and email are in a person’s settings. Nobody checks. If Mallory sets her configuration to say she is Nia, her commits will say “Nia Okafor”, and the log will happily agree. For a garden club that may not matter. For a project that ships software, it matters a great deal. This lesson looks at four defences, and at the habits that decide whether they work: proving who made a commit, protecting keys and tokens, catching secrets, and keeping dependencies fresh.

Signed commits

A signed commit carries a digital signature made with a private key that only its owner holds. Anyone with the matching public key can check that the commit really came from that key, and has not been changed since. Git supports signing with GPG keys, and since version 2.34 with SSH keys too. Hosting sites can show a badge, GitHub’s is called Verified, when they can check a signature against a public key you added to your account. The email in your Git settings usually has to match a verified email on the account, which is a common reason for an Unverified label.

The next session does the real thing with GPG. It creates two keys, one for Nia and one for Mallory, then makes three commits: one unsigned, one signed by Nia, and one signed by Mallory with Nia still named as the author. The log format asks Git for a one letter verdict on each signature. The key setup lines hide their noisy output, which is not needed here.

$ gpg --batch --pinentry-mode loopback --passphrase '' --quick-generate-key "Nia Okafor <nia@example.com>" ed25519 sign never 2>/dev/null
$ gpg --batch --pinentry-mode loopback --passphrase '' --quick-generate-key "Mallory <mallory@example.com>" ed25519 sign never 2>/dev/null
$ mkdir garden-notes
$ cd garden-notes
$ git init
Initialized empty Git repository in /home/nia/garden-notes/.git/
$ git config user.signingkey nia@example.com
$ echo "Beans: row 1" > plan.txt
$ git add plan.txt
$ git commit -q -m "Add plan (unsigned)"
$ echo "Carrots: row 2" >> plan.txt
$ git commit -q -S -am "Add carrots (signed by Nia)"
$ echo "Peas: row 3" >> plan.txt
$ git config user.signingkey mallory@example.com
$ git commit -q -S -am "Add peas (signed by Mallory)"
$ git config user.signingkey nia@example.com
$ git log --format="%G? %s"
G Add peas (signed by Mallory)
G Add carrots (signed by Nia)
N Add plan (unsigned)

On Nia’s own computer, both signatures check out, because both keys are in her keyring. That already teaches something: a good signature proves which key signed, not whether you should trust the key. The unsigned commit gets the letter N, for none. Now see how a teammate’s computer, which knows only Nia’s public key, sees the same history.

$ mkdir -m 700 /home/nia/teammate-keys
$ gpg --export nia@example.com | gpg --homedir /home/nia/teammate-keys --import 2>/dev/null
$ gpg --list-keys --with-colons nia@example.com 2>/dev/null | awk -F: '/^fpr/ {print $10":6:"; exit}' | gpg --homedir /home/nia/teammate-keys --import-ownertrust 2>/dev/null
$ GNUPGHOME=/home/nia/teammate-keys git log --format="%G? %s"
E Add peas (signed by Mallory)
G Add carrots (signed by Nia)
N Add plan (unsigned)
$ git log -1 --format="author: %an | signer: %GS"
author: Nia Okafor | signer: Mallory <mallory@example.com>

On the teammate’s computer, Nia’s commit is good, the unsigned one is none, and Mallory’s commit gets the letter E, which means the signature cannot be checked because the key is missing. The last line shows the trick. The author field says Nia, but the signer is Mallory. The signature exposed it. This is the entire value of signing: the name on a commit is a claim, and the signature is evidence. Other verdict letters exist, such as one for a bad signature and one for a good signature from an unknown key, and Git’s manual lists them.

Keys and tokens

To talk to GitHub safely, you use either an SSH key or an access token. GitHub’s help describes generating an SSH key with the key generation tool and a modern key type, ideally with a passphrase, then adding only the public half to your account. The private half never leaves your computer and is never pasted into a message. That tool is not installed on the machine that builds these lessons, so no key was generated here, and this is an outline. Tokens work like passwords with limits: they should have the smallest scope that does the job, and an expiry date.

Files that hold secrets must also be protected on your own computer. The listing below shows two copies of the same fake token file. On Unix style systems, the first number is the permission code: 644 lets other users on the computer read the file, and 600 lets only its owner read and write it. Private keys and token files should be the second kind. Windows manages file access differently, so check your system’s guidance.

$ cd ..
$ mkdir secrets-demo
$ cd secrets-demo
$ echo "token=FAKE-example-not-real" > token-open.txt
$ echo "token=FAKE-example-not-real" > token-closed.txt
$ chmod 644 token-open.txt
$ chmod 600 token-closed.txt
$ stat -c "%a %n" token-open.txt token-closed.txt
644 token-open.txt
600 token-closed.txt

A short script can also review a list of tokens against a simple policy. This one checks four made-up tokens for no expiry, an expiry date that has passed, an overly wide scope, and an age beyond ninety days. The ninety days is an invented policy for teaching, not a standard.

from datetime import date
TODAY = date(2026, 11, 2)
tokens = [
    {"name": "deploy-bot", "scope": "write one repo", "expires": date(2027, 2, 1), "created": date(2026, 10, 1)},
    {"name": "old-script", "scope": "everything", "expires": None, "created": date(2025, 11, 1)},
    {"name": "ci-reader", "scope": "read one repo", "expires": date(2026, 10, 1), "created": date(2026, 6, 1)},
    {"name": "my-laptop", "scope": "write all repos", "expires": date(2026, 12, 15), "created": date(2026, 8, 20)},
]
print("checked on:", TODAY.strftime("%a %-d %b %Y"))
problems = 0
for t in tokens:
    issues = []
    if t["expires"] is None: issues.append("never expires")
    elif t["expires"] < TODAY: issues.append("expired")
    if t["scope"] in ("everything", "write all repos"): issues.append("scope too wide")
    if (TODAY - t["created"]).days > 90: issues.append("older than 90 days")
    problems += bool(issues)
    print(t["name"] + ": " + ("ok" if not issues else ", ".join(issues)))
print("tokens needing action:", problems, "of", len(tokens))
checked on: Mon 2 Nov 2026
deploy-bot: ok
old-script: never expires, scope too wide, older than 90 days
ci-reader: expired, older than 90 days
my-laptop: scope too wide
tokens needing action: 3 of 4

The review flagged 3 of 4 tokens. Notice that two problems often arrive together: the oldest token never expires and has the widest scope. A regular review turns forgotten access into a short list of jobs.

Secret scanning and updates

  • Secret scanning. GitHub can look for known secret patterns in repositories and, with push protection, block a push that contains one. Which repositories get which features depends on visibility and plan, so check its current pages. Treat it as a second line of defence, never as your only one.
  • Your own scanner. The pattern scan from lesson 6 plus the hooks from lesson 23 catch most careless mistakes before they leave your computer.
  • Dependency updates. A configuration file lets the Dependabot service open pull requests that update your dependencies, and security updates for known vulnerabilities. You still read and test each one. Its options, limits and defaults change over time, so follow the current help.
  • Two step sign-in on every account that can publish your work.
Common mistake: signed means safe

Believing a green Verified badge means the code is safe. It only says that a known key signed the commit. A trusted person can still write a bug, and a stolen key can sign anything.

GPG run for real; the rest is outline

The names, keys and tokens are made up, and the keys exist only on the machine that built this lesson. SSH key generation and GitHub’s scanning and update services were not run. Features, plan rules and wording on GitHub change, so follow its help pages. This is an outline, not security advice for a real organisation.

Write your own token policy in three lines: the widest scope allowed, the longest life allowed, and how often you review. Then check every token you own against it.

Practice for this lesson

Check what you learned

Five quick questions. Pick an answer and you will see straight away whether it is right and why.

Why can a Git log not be trusted by names alone?

  1. Git encrypts names
  2. Names expire after a week
  3. Only GitHub can write names
  4. Anyone can set any name and email in their own settings

Mallory’s commit still named Nia as author.

What does a good signature prove?

  1. Which key signed the commit, and that it was not changed
  2. That the code has no bugs
  3. That the author is a good person
  4. That the commit is on GitHub

The signer line named Mallory even though the author line said Nia.

What did the letter E mean on the teammate’s computer?

  1. The commit was empty
  2. The commit was extra large
  3. The signature could not be checked because the key was missing
  4. The commit was encrypted

The teammate had only Nia’s public key.

Which half of an SSH key do you add to your account?

  1. The private half
  2. Both
  3. Neither
  4. The public half

The private half never leaves your computer.

Which permission code protects a token file better?

  1. 644, readable by other users
  2. 600, readable only by its owner
  3. Both are the same
  4. Neither matters

The token files showed both modes side by side.

Summary

  • A commit name is a claim; a signature is evidence of which key signed.
  • Share only public keys; protect private keys and token files.
  • Tokens need the smallest scope, an expiry and regular review.
  • Scanning and update services help, but they are second lines of defence.

Next lesson

Lesson 27 is about recovering from disasters.

Questions

Do I have to sign every commit?

No. Many teams do not. It is worth doing when authorship matters, such as for releases or for projects that others install.

Why does GitHub say Unverified?

Common causes are an email that does not match a verified email on the account, a key not added to the account, or a signing setup that is not enabled. Check its current help page for your case.

Can scanning find every secret?

No. It finds known patterns. A secret in an unusual format can slip through, so keep secrets out of repositories by habit.

Progress is saved in this browser.