SSH key generation and configuration

SSH keys are an essential tool in Git for authentication, enabling secure communication through asymmetric encryption. Generating and configuring SSH keys eliminates the need to enter passwords for each operation while enhancing repository access security.

Generating an SSH Key Pair

The first step is to generate an SSH key pair locally. Open a terminal and execute the following command:

ssh-keygen -t ed25519 -C "your_email@example.com"

If the system does not support the Ed25519 algorithm, use RSA instead:

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

After executing the command, you will be prompted to:

1. Choose a key storage path (default is ~/.ssh/id_ed25519)
2. Set a passphrase for the key (optional but recommended)

Once generated, two files will appear in the ~/.ssh directory:

• Private key file: id_ed25519
• Public key file: id_ed25519.pub

Viewing and Copying the Public Key

Use the following command to view the public key content:

cat ~/.ssh/id_ed25519.pub

Example output:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJl3B5YVhNz7JkR6XQ1wJ8Xz7Y6Lk7FtZw9TqYd0jKL your_email@example.com

Copy the entire content (including the algorithm type at the beginning and the comment at the end).

Adding the Key to ssh-agent

Ensure ssh-agent is running and add the key:

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

If a passphrase was set, you will need to enter it now.

Configuring Git Platforms

GitHub Configuration

1. Log in to GitHub and go to Settings.
2. Select SSH and GPG keys.
3. Click New SSH key.
4. Paste the public key content.

GitLab Configuration

1. Go to User Settings → SSH Keys.
2. Paste the public key and set an expiration date (optional).

Gitee Configuration

1. Navigate to Security Settings → SSH Public Key.
2. Fill in a title before pasting the content.

Multi-Account Configuration

When using different keys for different platforms:

1. Generate a second key pair:

ssh-keygen -t ed25519 -C "work@company.com" -f ~/.ssh/id_work

2. Create or modify the ~/.ssh/config file:

# Personal account
Host github.com-personal
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519

# Work account
Host github.com-work
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_work

3. Use the corresponding host when cloning repositories:

git clone git@github.com-work:company/project.git

Testing the Connection

Verify if the configuration is successful:

ssh -T git@github.com

A successful connection will display the authenticated username.

Troubleshooting Common Issues

Permission Issues

Ensure the key files have the correct permissions:

chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

Connection Refused

Check firewall settings or try verbose output:

ssh -vT git@github.com

Key Not Working

Confirm the URL is in SSH format:

git remote set-url origin git@github.com:user/repo.git

Key Rotation and Updates

Recommended steps for periodic key rotation:

1. Generate a new key pair.
2. Add the new public key to all platforms.
3. Test the new key and delete the old one once confirmed working.
4. Update the remote URL for all local repositories.

Automation in Deployment Scenarios

Using SSH keys in CI/CD environments:

// Node.js example: Automatically add a key via child_process
const { execSync } = require('child_process')
const fs = require('fs')

// Write the key content to a temporary file
fs.writeFileSync('/tmp/deploy_key', process.env.SSH_PRIVATE_KEY)
execSync('chmod 600 /tmp/deploy_key')

// Configure SSH
execSync(`ssh-add /tmp/deploy_key`)

Security Best Practices

1. Never share private keys.
2. Use different keys for different services.
3. Protect keys with strong passphrases.
4. Regularly review the list of authorized keys.
5. Use temporary keys on untrusted devices.