Git Remote Repository Operations: SSH Key Configuration for Connecting to GitHub/GitLab

When using Git for version control, we often need to interact with remote repositories (such as GitHub or GitLab), for example, cloning projects, pushing code, or pulling updates. Entering your account password every time you perform an operation is cumbersome, and SSH keys serve as the “security key” to solve this problem, allowing you to establish a trusted connection with the remote repository without repeatedly entering your password.

I. Why Use SSH Keys?¶

SSH keys are essentially a pair of encrypted “keys”:
- Private Key: Stored on your local computer, it is absolutely confidential and used to prove your identity.
- Public Key: Needs to be submitted to a remote repository (e.g., GitHub). The remote repository verifies the legitimacy of the private key through the public key.

The benefits of using SSH keys to connect to remote repositories:
- No need to manually enter your password, making operations more convenient.
- More secure than password authentication. The public-key encryption method reduces the risk of identity theft.

II. Generate SSH Key Pair¶

First, you need to generate a public-private key pair on your local computer.

1. Open the Terminal/Command Line Tool¶

Windows: Use Git Bash (usually installed with Git).
macOS/Linux: Directly open the “Terminal”.

2. Generate the Key¶

In the command line, execute the following command to generate an SSH key named id_ed25519 (the Ed25519 algorithm is currently recommended for high security and fast generation):

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

Command Explanation:
-t ed25519: Specifies the key type as Ed25519.
-C "your_email@example.com": Adds a comment (usually your GitHub/GitLab registered email, for easy distinction between different accounts).

After execution, you will be prompted to choose the key storage path (press Enter to use the default path: /c/Users/YourUsername/.ssh/id_ed25519) or enter a custom path.

3. Set a Passphrase (Optional)¶

The system may prompt you to enter a “Passphrase” to encrypt the private key. If it’s a personal computer and you use it frequently, it is recommended to leave it blank (press Enter directly); otherwise, you will need to enter the password every time you perform Git operations. If you are concerned about security, you can set a simple password.

4. View Public Key Content¶

After successful generation, the public key file is id_ed25519.pub, and you need to copy its content to the remote repository (GitHub/GitLab).

Windows/macOS/Linux: Execute the following command to directly print the public key content:

  cat ~/.ssh/id_ed25519.pub

Alternatively, open C:\Users\YourUsername\.ssh\id_ed25519.pub (Windows) or ~/.ssh/id_ed25519.pub (macOS/Linux) with a text editor (e.g., Notepad, VS Code), and copy the entire content.

III. Add the Public Key to SSH-Agent (Make the Private Key Take Effect Automatically)¶

To ensure the system automatically uses the private key to connect to the remote repository, you need to add the private key to SSH-Agent (the process that manages private keys).

1. Start SSH-Agent¶

macOS/Linux:

  eval "$(ssh-agent -s)"  # Start SSH-Agent

Windows (Git Bash): It usually starts automatically, so you can proceed to the next step directly.

2. Add the Private Key to the Agent¶

Execute the following command to add the private key id_ed25519 to the Agent:

ssh-add ~/.ssh/id_ed25519

If you set a Passphrase, you will be prompted to enter the password here.

IV. Add the Public Key to the Remote Platform (GitHub/GitLab)¶

Now, you need to copy the public key to the remote repository to inform them “I can trust this key”. The following are the specific steps for GitHub and GitLab:

1. Taking GitHub as an Example¶

Open the GitHub website, log in, click your avatar in the top right corner → select “Settings”.
In the left menu, find “SSH and GPG keys” → click “New SSH key”.
Title: Fill in an identifier (e.g., “My Windows Computer” or “MacBook Pro”) to distinguish different devices.
Key: Paste the public key content you just copied (the content in id_ed25519.pub).
Click “Add SSH key” to complete the addition.

2. Similar Operations for GitLab¶

Open the GitLab website, log in, click your avatar in the top right corner → “Settings” → “SSH Keys”.
Title: Fill in an identifier (e.g., “Work Computer”).
Key: Paste the public key content.
Click “Add Key” to complete the addition.

V. Test if the Connection is Successful¶

After configuration, use the following command to test whether the SSH connection works properly:

ssh -T git@github.com  # For GitHub
# Or
ssh -T git@gitlab.com  # For GitLab

If successful: You will receive a welcome message like “Hi [Username]! You’ve successfully authenticated…”.
If failed: Check if the public key was correctly added to the remote platform or if you entered the correct email/account.

VI. Troubleshooting Common Issues¶

“Permission denied” prompt: The public key may not have been added to the remote platform. Recheck the public key content and platform configuration.
Cannot find the .ssh directory: The key generation path was incorrect. The default path is usually the .ssh folder under the user directory. You can directly enter ~/.ssh in the file manager to view it.
Private key access denied: Check if the Agent is running and the private key has been added (execute ssh-add -l to view the list of added private keys).

Now you have completed the SSH key configuration. In the future, you won’t need to enter your password when cloning or pushing code! If you encounter other issues, feel free to refer to the official documentation of the remote platform or the error messages from the Git command line; this will help you troubleshoot problems more efficiently.