how to configure an ssh key and customize the path of an ssh authentication key - Alibaba Cloud DevOps

Apsara Devops Codeup repositories support the HTTP(S) and Secure Shell (SSH) access protocols. The SSH protocol provides secure, password-free authentication and offers better performance than the HTTP(S) protocol. This topic describes how to configure and use an SSH key to push and pull code in Codeup.

Prerequisites

Before you can use the SSH protocol to work with a code repository, you must generate an SSH public key and upload it to your Apsara Devops account.

To access Codeup using the SSH protocol, you must meet the following requirements.

Git version 1.9 or later is installed on your local machine. To check the installed version, run the git --version command.
An OpenSSH client is installed on your local machine. GNU/Linux, macOS, and Windows 10 have OpenSSH pre-installed.
Keep your SSH version up to date. Versions earlier than 6.5 may have security vulnerabilities because they use MD5 signatures.

Important

If you are a Windows user, use WSL (requires Windows 10 or later) or Git Bash when you run Git commands.

Background information

Codeup supports the following SSH encryption algorithm types:

Algorithm type	Public key	Private key
ED25519 (Recommended)	id_ed25519.pub	id_ed25519
RSA (Not recommended)	id_rsa.pub	id_rsa

Step 1: Check for existing SSH keys

Before you generate a new SSH key, check for an existing key that you can use. SSH key pairs are typically stored in the root directory of the local user.

On Linux and macOS, run the following command to check for an existing public key. On Windows, run the command in WSL (requires Windows 10 or later) or Git Bash:

ED25519 algorithm

cat ~/.ssh/id_ed25519.pub

RSA algorithm

cat ~/.ssh/id_rsa.pub

If the command returns a long string that starts with ssh-ed25519 or ssh-rsa, a local public key already exists. You can skip Step 2 and proceed to Step 3.

Step 2: Generate an SSH key

If the command in Step 1 does not return a string, a usable SSH key does not exist on your local machine. In this case, you must generate a new SSH key.

Open a terminal and run the ssh-keygen -t command.
Enter the key algorithm type and an optional comment. The comment appears in the .pub file. You can use your email address as the comment.

To generate a key pair using the ED25519 algorithm, run the following command:
```
ssh-keygen -t ed25519 -C "<your_comment>"
```
To generate a key pair using the RSA algorithm, run the following command:
```
ssh-keygen -t rsa -C "<your_comment>"
```

Press Enter to accept the default file path for the SSH key.

For the ED25519 algorithm, the default path is shown below:
```
Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/user/.ssh/id_ed25519):
```
The default path for the private key is /home/user/.ssh/id_ed25519, and the corresponding public key is /home/user/.ssh/id_ed25519.pub.
For the RSA algorithm, the default path is shown below:
```
Generating public/private rsa key pair.
Enter file in which to save the key (/home/user/.ssh/id_rsa):
```
The default path for the private key is /home/user/.ssh/id_rsa, and the corresponding public key is /home/user/.ssh/id_rsa.pub.

Set a passphrase for the key.
```
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
```
The passphrase is empty by default. You can use a passphrase to protect the private key file. If you do not want to enter the passphrase every time you use the SSH protocol, leave the passphrase empty when you create the key.
Press Enter to create the key pair.

Warning

The key is used for authentication. Keep your private key secure. The public key file ends with the .pub extension and can be shared. Do not disclose the private key file, which does not have the .pub extension, to anyone.

Step 3: Copy the public key

Instead of manually copying the public key from the command-line output, you can use a command to copy it to your clipboard. Run the command for your operating system:

Windows (in WSL or Git Bash):

cat ~/.ssh/id_ed25519.pub | clip

macOS:

tr -d '\n' < ~/.ssh/id_ed25519.pub | pbcopy

GNU/Linux (requires xclip):

xclip -sel clip < ~/.ssh/id_ed25519.pub

Step 4: Add the public key to Codeup

Log in to Apsara Devops. In the upper-right corner, click your profile picture and select Personal Settings. Then, select SSH Public Key.
Add the generated SSH public key.

SSH Public Key
Note
Copy the entire public key, from ssh- to your email address.
Title: A custom name to identify the key.
Applicable Scope: The scope of the key, which can be read/write or read-only. If set to read-only, the key can be used only to pull code, not to push code.
Expiration Time: The date on which the key expires. After this date, the key becomes invalid.

Click Add to save the key.

FAQ

If I have multiple local keys, how can I automatically select the correct key for a specific platform?

If you have multiple local keys and do not set authentication rules, your local machine may randomly select a key for authentication. This can cause authentication failures.

We recommend that you define the path to the authentication key in the following scenarios:

You have multiple keys for different Apsara Devops accounts.
You have multiple keys for different code platforms, such as GitLab, GitHub, and Apsara Devops.

Define authentication key path rules

Open a local terminal and edit the ~/.ssh/config file. On Windows, use WSL (requires Windows 10 or later) or Git Bash. Edit the file in the following format:

# Apsara Devops example user 1
HostName codeup.aliyun.com
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/id_ed25519
  
# Apsara Devops example user 2, with alias codeup-user-2
Host codeup-user-2
HostName codeup.aliyun.com
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/codeup_user_2_ed25519

# GitLab platform
HostName gitlab.com
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/gitlab_ed25519

With this configuration, the SSH client uses the specified key for authentication when you access a platform. This lets you use different local SSH keys for different accounts on the same platform, or for different platforms.

To access Apsara Devops, use an alias to select a key because the HostName is the same for both accounts.
To access GitLab, the key is selected based on the HostName.

# Access Apsara Devops. Uses the ~/.ssh/id_ed25519.pub key.
git clone gi*@codeup.aliyun.com:example/repo.com

# Access Apsara Devops with the alias codeup-user-2. Uses the ~/.ssh/codeup_user_2_ed25519 key.
git clone git@codeup-user-2:example/repo.com

# Access the GitLab platform. Uses the ~/.ssh/gitlab_ed25519 key.
git clone gi*@gitlab.com:example/repo.com