# GitHub SSH Authentication and Commit Signing


## About SSH

SSH (Secure Shell) is an encrypted protocol for connecting to another computer. It normally uses port 22.

For GitHub, SSH can be used to authenticate access to repositories. The local machine keeps the private key, while GitHub stores the corresponding public key.

SSH authentication answers: “Can you connect to GitHub and push code?”

Commit signing answers: “Was this commit created by you, and has it been changed?”

These are separate features and do not replace each other.

## Using an SSH key for GitHub authentication

### When it is useful

When a repository uses an address such as `git@github.com:owner/repository.git`:

- SSH keys authenticate the connection.
- SSH avoids entering a password or Personal Access Token for every operation.
- The communication channel is encrypted.

### How it works

- The private key stays on your computer and must remain secret.
- GitHub stores your public key.
- During connection setup, GitHub sends a challenge.
- Your private key answers the challenge, and GitHub verifies it with the public key.

### What it does not prove

SSH authentication only applies when the connection is established. It does not sign or protect the commit itself.

Anyone can change `git config user.name` and `git config user.email` and create a commit that appears to use your name. If that person pushes with their own authorized SSH key, GitHub can authenticate the account that pushed the commit, but it cannot use the author name alone to prove who wrote it.

### Basic setup

```bash
# Generate an Ed25519 key (recommended over RSA)
ssh-keygen -t ed25519 -C "your-github-email"

# Start the SSH agent
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# Print the public key
cat ~/.ssh/id_ed25519.pub
```

Add the complete public key in **GitHub Settings -> SSH and GPG keys -> New SSH key**. Select **Authentication Key** as the key type.

Test the connection:

```bash
ssh -T git@github.com
```

## Git commit signing

### What it proves

A digital signature is attached to the commit or tag data. It can show that:

- The commit was created by someone holding the signing private key.
- The signed data has not been changed after signing.
- GitHub can display the green **Verified** label when the signature is valid.

Git originally focused on GPG signatures. Git 2.34 and later also support SSH signatures, so an existing SSH key can be used without generating a separate GPG key.

If you want to use one SSH key for both GitHub access and commit signing, add it twice in GitHub: once as an **Authentication Key** and once as a **Signing Key**.

### Configure SSH signing globally

```bash
# Use SSH signatures instead of the default GPG format
git config --global gpg.format ssh

# Use the public key as the signing key
git config --global user.signingkey ~/.ssh/id_ed25519.pub

# Sign every commit automatically
git config --global commit.gpgsign true

# Sign tags automatically
git config --global tag.gpgsign true
```

### Add the signing key in GitHub

Open **Settings -> SSH and GPG keys -> New SSH key**.

Enter any title, select **Signing Key** as the key type, and paste the complete contents of `id_ed25519.pub`.

Do not select **Authentication Key** for this second entry. The same public key may appear twice, but the two entries have different purposes.

### Verify a signed commit

```bash
# Create an empty test commit
git commit --allow-empty -m "test ssh signed commit"

# Show the signature information
git log --show-signature -1

git push
```

After GitHub verifies the signature, the commit should show the **Verified** label.