# Signing your commits

## Why commit signing is required[​](#why-commit-signing-is-required "Direct link to Why commit signing is required")

Apps are automatically deployed to production from the `prod` branch, but only when pushed by admin users with signed commits. This security measure ensures that only trusted and verified code reaches your production environment.

Who needs this?

Only admin users who deploy to production need to sign their commits. Regular developers working on the `main` branch don't need signed commits.

## Setup process[​](#setup-process "Direct link to Setup process")

<!-- -->

### Step 1: Generate an SSH key[​](#step-1-generate-an-ssh-key "Direct link to Step 1: Generate an SSH key")

In your terminal (Codespace or local):

```
ssh-keygen -t ed25519 -C "your-email@your-org.com" -f ~/.ssh/id_ed25519
```

This creates two files:

* `~/.ssh/id_ed25519` (private key - keep this secret)
* `~/.ssh/id_ed25519.pub` (public key - this gets added to GitHub)

### Step 2: Add the public key to GitHub[​](#step-2-add-the-public-key-to-github "Direct link to Step 2: Add the public key to GitHub")

1. **Copy your public key:**

   * Run this command and copy its output for pasting into GitHub on the next step:

```
cat ~/.ssh/id_ed25519.pub
```

2. **Add to GitHub:**

   * Go to: <https://github.com/settings/ssh/new>
   * Give it a descriptive title (e.g., "Codespace SSH signing key")
   * Set key type to be "Signing Key" (not "Authentication Key")
   * Paste the public key content (copied in previous step)
   * Click "Add SSH key"

![GitHub SSH key settings page with the key type set to Signing Key and the public key pasted](/assets/images/gh-signing-key-f136ed88e0866829df1fcffda4db16c0.png)

### Step 3: Configure Git for signing[​](#step-3-configure-git-for-signing "Direct link to Step 3: Configure Git for signing")

Tell Git to use your SSH key for signing all commits:

```
git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519
git config --global commit.gpgsign true
```

### Step 4: Test your setup[​](#step-4-test-your-setup "Direct link to Step 4: Test your setup")

Make a test commit to verify signing works:

```
git commit --allow-empty -m "Test signed commit"
git push
```

**Verify it worked:** Check your commit on GitHub - you should see a ✅ **Verified** badge next to the commit.

![GitHub commit history showing a Verified badge next to the signed commit](/assets/images/gh-verified-commit-b48e5242d9311427de106f32f60dabc5.png)

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

**No verified badge appearing?**

* Ensure your email in the SSH key matches your GitHub account email
* Check that you pushed to the correct repository
* Verify the SSH key was added correctly to your GitHub account

**Git signing errors?**

* Make sure the SSH key file path is correct: `~/.ssh/id_ed25519`
* Verify the private key file exists and has proper permissions
* Try generating a new SSH key if issues persist

**Working in multiple environments?**

* The SSH key setup needs to be done separately for each environment (local machine, different Codespaces)
* You can add multiple SSH keys to your GitHub account