How to Manage GitHub SSH Keys Using 'gh ssh-key' (with examples)

The gh ssh-key command is part of GitHub’s official command-line interface (CLI), which provides a streamlined way to manage SSH keys associated with your GitHub account. This suite of commands allows developers to perform common tasks related to SSH keys directly from the terminal, eliminating the need to navigate through the GitHub web interface manually. Whether you need to list, add, or customize your SSH keys, gh ssh-key offers precise control, making it a valuable tool for anyone managing their Git repositories on GitHub.

Use case 1: Display Help

Code:

gh ssh-key

Motivation:

Whenever we learn a new command or need to recall its options later, consulting a help guide is crucial. Using gh ssh-key without any additional arguments will display its help information, detailing the syntaxes and options available under this command set. This is important for new users to get an overview of what operations they can perform and also acts as a quick reference for experienced users.

Explanation:

The command gh ssh-key by itself acts as a help trigger. It lists out all subcommands and available options along with short descriptions. Since no additional arguments or flags are provided, it defaults to displaying the help content.

Example Output:

usage: gh ssh-key <command> [flags]

Manage GitHub SSH keys

Commands
  list        Display SSH keys in your GitHub account
  add         Add an SSH key to your GitHub account

Flags
  -h, --help  Show help for command

Use case 2: List SSH Keys for the Currently Authenticated User

Code:

gh ssh-key list

Motivation:

As a developer managing multiple keys or ensuring operational security, it’s crucial to regularly monitor the SSH keys associated with your GitHub account. Listing SSH keys allows you to review all keys currently linked to your account, helping detect unauthorized keys or manage key rotation policies.

Explanation:

By appending list to the gh ssh-key command, you instruct it to fetch and display all SSH keys associated with your authenticated GitHub account. This operation does not require any additional arguments or parameters, simplifying the process of SSH key management.

Example Output:

TITLE     ID        KEY
laptop    12345678  ssh-rsa AAA...123 user@laptop
desktop   87654321  ssh-rsa AAA...456 user@desktop

Use case 3: Add an SSH Key to the Currently Authenticated User’s Account

Code:

gh ssh-key add path/to/key.pub

Motivation:

Adding your SSH key to your GitHub account is a necessary step to establish a secure, password-less communication between your local environment and GitHub servers. This provides a way to push changes to repositories or access private data remotely without compromising security.

Explanation:

This particular use case demonstrates how to add an SSH key file, located at path/to/key.pub, to your GitHub account. The add subcommand tells GitHub CLI that you want to add a new key, while path/to/key.pub is the relative or absolute path of your SSH public key file.

Example Output:

✓ Added SSH key 'key.pub' to your account

Use case 4: Add an SSH Key with a Specific Title to the Currently Authenticated User’s Account

Code:

gh ssh-key add --title "My Laptop Key" path/to/key.pub

Motivation:

When managing several SSH keys, it is advisable to assign specific titles to each key for easy identification and management. Titles help differentiate between keys from different machines or environments, simplifying the task of reviewing or revoking keys in the future.

Explanation:

In this command, --title "My Laptop Key" specifies a custom title for the SSH key. This descriptive title helps differentiate it from other keys by providing context. The path/to/key.pub argument indicates the file path to the SSH public key you intend to add to your GitHub account.

Example Output:

✓ Added SSH key 'My Laptop Key' to your account

Conclusion:

The gh ssh-key command is a versatile tool designed for developers who need to manage their GitHub SSH keys directly from the command line. By understanding and utilizing the various subcommands and options available, users can efficiently manage and audit their keys, thereby ensuring both convenience and security in their software development workflow.