From 084ccf0177221112da68f2074818a2ef775487bd Mon Sep 17 00:00:00 2001
From: yubiuser <github@yubiuser.dev>
Date: Sun, 3 May 2026 16:41:08 +0200
Subject: [PATCH 1/2] Add notice about test requirement

Signed-off-by: yubiuser <github@yubiuser.dev>
---
 docs/guides/github/index.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/guides/github/index.md b/docs/guides/github/index.md
index f662869a3..544db1872 100644
--- a/docs/guides/github/index.md
+++ b/docs/guides/github/index.md
@@ -25,6 +25,7 @@ When requesting or submitting new features, first consider whether it might be u
 - Check the codebase to ensure that your feature doesn't already exist.
 - Check the pull requests to ensure that another person hasn't already submitted the feature or fix.
 - Read and understand the [DCO guidelines](./dco.md)  for the project.
+- Before a pull requets can be accepted, the repo-specific tests need to pass. Please test them locally first.
 
 ### Technical Requirements
 

From b05cd6c3c5ab22396589829b8dcc678ee49d2e3d Mon Sep 17 00:00:00 2001
From: yubiuser <github@yubiuser.dev>
Date: Sun, 3 May 2026 16:58:54 +0200
Subject: [PATCH 2/2] Add instructions how to sign a commit.

Assisted-by: Claude:claude-sonnet-4
Signed-off-by: yubiuser <github@yubiuser.dev>
---
 docs/guides/github/index.md |  1 +
 docs/guides/github/sign.md  | 59 +++++++++++++++++++++++++++++++++++++
 mkdocs.yml                  |  1 +
 3 files changed, 61 insertions(+)
 create mode 100644 docs/guides/github/sign.md

diff --git a/docs/guides/github/index.md b/docs/guides/github/index.md
index 544db1872..7f1bf2e55 100644
--- a/docs/guides/github/index.md
+++ b/docs/guides/github/index.md
@@ -25,6 +25,7 @@ When requesting or submitting new features, first consider whether it might be u
 - Check the codebase to ensure that your feature doesn't already exist.
 - Check the pull requests to ensure that another person hasn't already submitted the feature or fix.
 - Read and understand the [DCO guidelines](./dco.md)  for the project.
+- Our repos require users to (cryptographically) sign their commits (which is different to sign-off!). Our recommendation is to use `ssh` keys. Basics steps are [outlined here](./sign.md).
 - Before a pull requets can be accepted, the repo-specific tests need to pass. Please test them locally first.
 
 ### Technical Requirements
diff --git a/docs/guides/github/sign.md b/docs/guides/github/sign.md
new file mode 100644
index 000000000..50f4ccba5
--- /dev/null
+++ b/docs/guides/github/sign.md
@@ -0,0 +1,59 @@
+# Signing Git Commits with SSH Keys
+
+## Why Sign Commits?
+
+Signing commits provides:
+
+- **Authentication**: Proves the commit actually came from you
+- **Integrity**: Ensures the commit content hasn't been tampered with
+- **Trust**: GitHub displays a "Verified" badge for signed commits
+- **Security**: Protects against commit spoofing attacks
+
+## Prerequisites
+
+- An SSH key pair (if you don't have one, generate with `ssh-keygen -t ed25519 -C "your_email@example.com"`)
+- SSH key added to your GitHub account
+
+## Setup Instructions
+
+### 1. Configure Git to Use SSH Signing
+
+```bash
+# Set SSH as the signing format
+git config --global gpg.format ssh
+
+# Specify your SSH public key for signing
+git config --global user.signingkey /PATH/TO/.SSH/KEY.PUB
+
+# Optional: Enable automatic signing for all commits
+git config --global commit.gpgsign true
+```
+
+### 2. Add SSH Key to GitHub
+
+1. Copy your SSH public key: `/PATH/TO/.SSH/KEY.PUB`
+2. Go to GitHub → Settings → SSH and GPG keys
+3. Click "New SSH key"
+4. Set Key type to "Signing Key"
+5. Paste your public key and save
+
+### 3. Sign Commits
+
+```bash
+# Sign a single commit
+git commit -S -m "Your commit message"
+
+# If auto-signing is enabled, just commit normally
+git commit -m "Your commit message"
+```
+
+## Verification
+
+- On GitHub: Look for the "Verified" badge next to your commits
+- Locally: `git log --show-signature` displays signature information
+
+
+## Notes
+
+- SSH signing requires Git 2.34+ and GitHub support
+- Your SSH key must be added as a "Signing Key" type in GitHub, not just an authentication key
diff --git a/mkdocs.yml b/mkdocs.yml
index e5c157fdc..c3710cd07 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -174,6 +174,7 @@ nav:
     - 'Developer Certificate of Origin (DCO)': guides/github/dco.md
     - 'How to sign-off commits': guides/github/how-to-signoff.md
     - 'How to fork and rebase': guides/github/how-to-fork-rebase.md
+    - 'How to sign commits': guides/github/sign.md
   - 'Guides':
     - 'DNS':
       - 'unbound': guides/dns/unbound.md