Connecting via SSH

Unlike the Getting Started guide, this page provides a deeper reference for using SSH with Git, including key management, configuration, commit signing, and security best practices.

SSH and Git#

SSH is used by Git for secure, passwordless authentication when interacting with remote repositories. Instead of passwords, SSH relies on asymmetric key pairs:

• Private key — stored securely on your machine, never shared
• Public key — added to your OpenCommit account

When you connect, your client proves possession of the private key without ever transmitting it. This is fundamentally more secure than password-based authentication.

Supported Key Types#

OpenCommit enforces a strict key policy. Only the following key types are accepted:

Ed25519 is the recommended key type. RSA and DSA keys are not accepted under any circumstances.

Generating a Key#

Generate an Ed25519 key pair:

ssh-keygen -t ed25519 -C "your-email@example.com"

You will be prompted for a file location (default: ~/.ssh/id_ed25519) and an optional passphrase. A passphrase is strongly recommended as it encrypts your private key at rest, protecting it if your machine is ever compromised.

SSH Agent#

The SSH agent manages your keys in memory, so you do not need to re-enter your passphrase on every operation.

Start the agent and add your key:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

List currently loaded keys:

ssh-add -l

On macOS, you can persist the key across reboots by adding the following to ~/.ssh/config:

Host *
    UseKeychain yes
    AddKeysToAgent yes

SSH Config File#

The ~/.ssh/config file gives you fine-grained control over how SSH behaves per host. A basic OpenCommit entry looks like this:

Host opencommit
    HostName opencommit.eu
    User git
    IdentityFile ~/.ssh/id_ed25519

With this in place, you can use the shorthand alias in Git commands:

git clone opencommit:username/repository.git

git clone git@opencommit.eu:username/repository.git

This is especially useful if you work with multiple Git forges or accounts.

Using Multiple Keys#

If you maintain separate keys for different services or identities, assign them explicitly in ~/.ssh/config:

Host github
    HostName github.com
    IdentityFile ~/.ssh/id_github

Host opencommit
    HostName opencommit.eu
    IdentityFile ~/.ssh/id_opencommit

This prevents SSH from offering the wrong key and avoids authentication failures caused by key order or agent defaults.

Known Hosts and Host Key Verification#

When you connect to OpenCommit for the first time, SSH will ask you to verify the server’s host key fingerprint:

The authenticity of host 'opencommit.eu' can't be established.
ED25519 key fingerprint is SHA256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Are you sure you want to continue connecting (yes/no)?

Do not blindly accept this prompt.
Verify the fingerprint against the official OpenCommit published fingerprints before typing yes. Accepting an unverified fingerprint exposes you to a man-in-the-middle attack.

Once accepted, the host key is stored in ~/.ssh/known_hosts. On subsequent connections, SSH will silently verify the server’s identity against this stored value. If the key ever changes unexpectedly, SSH will refuse the connection and warn you — do not override this warning without first confirming with the OpenCommit Foundation that a key rotation has taken place.

To manually inspect your known hosts file:

ssh-keygen -l -F opencommit.eu

To remove a stale or rotated entry:

ssh-keygen -R opencommit.eu

Testing and Debugging Connections#

Test authentication:

ssh -T git@opencommit.eu

If successful, you will receive a confirmation message. For verbose output useful in diagnosing failures:

ssh -vT git@opencommit.eu

The -v flag (increase to -vv or -vvv for more detail) shows the full handshake, which key was offered, and at what point a failure occurred.

SSH Commit Signing#

Git supports signing commits and tags using SSH keys as an alternative to GPG. This is the recommended signing method on OpenCommit.

SSH authentication keys and SSH signing keys serve different purposes. You may use the same key for both, but some users and organisations prefer to keep them separate.

Why sign commits?#

Signed commits provide cryptographic proof that a commit was authored by the holder of a specific key. On OpenCommit, verified commits are marked with a Verified badge in the repository interface, giving collaborators and maintainers confidence in the provenance of contributions.

Configuring SSH signing#

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

With commit.gpgsign and tag.gpgsign set to true, all commits and tags are signed automatically without requiring the -S flag each time.

Setting SSH signing as your default#

The OpenCommit Foundation recommends enabling SSH signing by default for all contributors. It simplifies key management (no separate GPG key required), and aligns your signing identity directly with your authentication identity.

Allowed signers#

For local verification of signed commits on your own machine, Git requires an allowed signers file. This file is not used by OpenCommit itself; it is only used by your local Git client when verifying SSH signatures.

git config --global gpg.ssh.allowedSignersFile ~/.ssh/allowed_signers

Add entries in the following format:

your-email@example.com namespaces="git" ssh-ed25519 AAAA...

You can then verify a commit locally with:

git verify-commit HEAD

Verification Badges on OpenCommit#

When SSH signing is correctly configured and your public key is registered in your OpenCommit account, commits pushed to OpenCommit may display a Verified badge. This badge confirms that:

• The commit was signed with a key associated with your account
• The signature is cryptographically valid
• OpenCommit was able to verify the signature successfully

Unverified commits are not blocked by default, but the absence of a badge is visible to repository maintainers and collaborators. Projects hosted on OpenCommit may choose to require verified commits through branch protection or repository policy.

Security Best Practices#

• Always use a passphrase on your private key
• Never share or copy your private key to another machine; generate a new key per device instead
• Rotate keys periodically, or immediately if a device is lost or compromised
• Revoke old keys promptly via your OpenCommit profile settings
• Do not store private keys in cloud-synced directories (e.g., Dropbox, iCloud Drive, Google Drive)
• Verify host fingerprints on first connection; do not skip this step
• Use Ed25519 exclusively if at all possible

Common Issues#

Further Reading#

• man ssh
• man ssh_config
• man ssh-keygen
• man ssh-agent
• OpenSSH project