doc: improve commit signing guidelines in CONTRIBUTING.md

Signed-off-by: Shubhika Garg <shubhika.garg@openairinterface.org>
2026-07-13 04:30:28 +00:00 · 2026-06-18 11:36:42 +02:00
parent 840abd0048
commit a5f60811c5
1 changed files with 109 additions and 16 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,6 +1,6 @@
 <!-- SPDX-License-Identifier: CC-BY-4.0 -->

-# Contributing to OpenAirInterface
+# Contributing to Duranta

 We want to make contributing to this project as easy and transparent as possible.

@@ -18,41 +18,134 @@ We want to make contributing to this project as easy and transparent as possible

 ## Commit Guidelines

+Every pull request must pass two CI checks before it can be merged:
+
+1. **[Developer Certificate of Origin (DCO)](https://en.wikipedia.org/wiki/Developer_Certificate_of_Origin)**:
+   Each commit must include a `Signed-off-by:` trailer in the commit message.
+   Use `git commit -s` (or `--signoff`).
+
+2. **[Verified commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification)**:
+   Each commit must be cryptographically signed using SSH or GPG keys to confirm
+   its origin.
+
 ### Signing Commits

-To sign commits:
+GitHub supports commit signing using either SSH keys or GPG keys.
+For more information, see the
+[GitHub documentation](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits).

-You can also get the verified label on your commits via using [SSH keys or GPG
-keys](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits)
+Before configuring commit signing:
+
+- Generate an SSH key pair or GPG key pair.
+- Add your public key to your GitHub account.
+- Verify your GitHub email address (required for “Verified” commits to work).
+- If using SSH signing, ensure the key is registered in GitHub for:
+    - Authentication (SSH and GPG keys)
+    - Signing commits (Signing Keys)
+
+> **NOTE:**
+> Adding an SSH key for repo access does not automatically enable commit signing.
+> The key must also be added under GitHub's Signing Keys settings.
+
+
+To ensure commits show as Verified on GitHub:
+
+- Your `git config user.email` must match a GitHub email
+- That email must be verified in your GitHub account
+
+For more information, see the
+[GitHub Docs](https://docs.github.com/en/account-and-profile/how-tos/email-preferences/verifying-your-email-address)
+
+Configure your repository's `.git/config`:
+
+```ini
+# Edit the git configuration

-```
-# Edit .git/config in the git repository you are working on
-# Add the user section
 [user]
    name = YOUR NAME
-    email = YOUR EMAIL ADDRESS
+    email = YOUR VERIFIED EMAIL ADDRESS

-# If you use a signing key, use the below configuration instead
-[user]
-    name = YOUR NAME
-    email = YOUR EMAIL ADDRESS
-    signingkey = LOCATION OF SSH KEYS or GPG KEY
+    # REQUIRED for commit signing
+    # Use ONE signing method (SSH or GPG)
+
+    signingkey = YOUR_SIGNING_KEY
+
+    # Examples:
+    # SSH signing:
+    # signingkey = ~/.ssh/id_ed25519.pub
+
+    # GPG signing:
+    # signingkey = YOUR_GPG_KEY_ID

 [gpg]
-    format = ssh
+    # REQUIRED: defines signing method (SSH or GPG)
+
+    format = YOUR_SIGNING_FORMAT
+
+    # Examples:
+    # SSH signing:
+    # format = ssh
+
+    # GPG signing:
+    # format = openpgp

 [commit]
    gpgsign = true
 ```

-> **NOTE:** If your commits are not signed the CI framework will not accept the PR.
+> The private key is used automatically by SSH/Git when signing commits (SSH only).

+#### Verifying Signed Commits
+
+You can verify that commits are properly signed locally using:
+
+```bash
+git log --show-signature
+```
+
+GitHub should also display a Verified badge next to signed commits once the
+signing key has been correctly configured in your account.
+
+##### SSH Signature Verification (`allowed_signers`)
+
+For SSH commit signing, local Git verification may require an `allowed_signers`
+file. This is only used for local verification in Git and is not required
+by GitHub.
+
+If you see errors such as:
+
+```text
+No principal matched
+Can't check signature
+error: gpg.ssh.allowedSignersFile needs to be configured
+```
+you may need to configure it.
+
+Create the file and add your signing identity:
+
+```bash
+mkdir -p ~/.config/git
+touch ~/.config/git/allowed_signers
+echo "user@example.com ssh-ed25519 AAAACexamplekeystringhere" > ~/.config/git/allowed_signers
+```
+
+Enable it in local repository Git config:
+
+```bash
+git config gpg.ssh.allowedSignersFile ~/.config/git/allowed_signers
+```
+
+> **NOTE:**
+> This is only for local Git signature verification and does not affect GitHub,
+> or remote repository behavior.
+
+> **NOTE:** If your commits are not signed, the CI framework will not accept the PR.
 For more information regarding contribution guidelines
 please check [this document](doc/code-style-contrib.md)

 ## License

-By contributing to OpenAirInterface, you agree that your contributions will be
+By contributing to Duranta, you agree that your contributions will be
 licensed under

 1. [CSSL v1.0 license](LICENSES/preferred/CSSL-v1.0.txt): for RAN and UE