cleanup SSH key details
This commit is contained in:
parent
034c649682
commit
746ccb2f83
|
@ -13,7 +13,7 @@ read [this nice tutorial by DigitalOcean](https://www.digitalocean.com/community
|
|||
|
||||
## Locating an existing SSH key pair
|
||||
|
||||
Before generating a new SSH key check if your system already has one
|
||||
Before generating a new SSH key pair check if your system already has one
|
||||
at the default location by opening a shell, or Command Prompt on Windows,
|
||||
and running the following command:
|
||||
|
||||
|
@ -23,43 +23,49 @@ and running the following command:
|
|||
type %userprofile%\.ssh\id_rsa.pub
|
||||
```
|
||||
|
||||
**GNU/Linux / macOS / PowerShell:**
|
||||
**Git Bash on Windows / GNU/Linux / macOS / PowerShell:**
|
||||
|
||||
```bash
|
||||
cat ~/.ssh/id_rsa.pub
|
||||
```
|
||||
|
||||
If you see a string starting with `ssh-rsa` you already have an SSH key pair
|
||||
and you can skip the next step **Generating a new SSH key pair**
|
||||
and continue onto **Copying your public SSH key to the clipboard**.
|
||||
and you can skip the generate portion of the next section and skip to the copy
|
||||
to clipboard step.
|
||||
If you don't see the string or would like to generate a SSH key pair with a
|
||||
custom name continue onto the next step.
|
||||
|
||||
>
|
||||
**Note:** Public SSH key may also be named as follows:
|
||||
- `id_dsa.pub`
|
||||
- `id_ecdsa.pub`
|
||||
- `id_ed25519.pub`
|
||||
|
||||
## Generating a new SSH key pair
|
||||
|
||||
1. To generate a new SSH key, use the following command:
|
||||
1. To generate a new SSH key pair, use the following command:
|
||||
|
||||
**GNU/Linux / macOS:**
|
||||
**Git Bash on Windows / GNU/Linux / macOS:**
|
||||
|
||||
```bash
|
||||
ssh-keygen -t rsa -C "GitLab" -b 4096
|
||||
ssh-keygen -t rsa -C "your.email@example.com" -b 4096
|
||||
```
|
||||
|
||||
**Windows:**
|
||||
|
||||
On Windows you will need to download
|
||||
Alternatively on Windows you can download
|
||||
[PuttyGen](http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html)
|
||||
and follow this [documentation article][winputty] to generate a SSH key pair.
|
||||
and follow [this documentation article][winputty] to generate a SSH key pair.
|
||||
|
||||
1. Next, you will be prompted to input a file path to save your key pair to.
|
||||
1. Next, you will be prompted to input a file path to save your SSH key pair to.
|
||||
|
||||
If you don't already have an SSH key pair use the suggested path by pressing
|
||||
enter. Using the suggested path will allow your SSH client
|
||||
to automatically use the key pair with no additional configuration.
|
||||
enter. Using the suggested path will normally allow your SSH client
|
||||
to automatically use the SSH key pair with no additional configuration.
|
||||
|
||||
If you already have a key pair with the suggested file path, you will need
|
||||
to input a new file path and declare what host this key pair will be used
|
||||
for in your `.ssh/config` file, see **Working with non-default SSH key pair paths**
|
||||
If you already have a SSH key pair with the suggested file path, you will need
|
||||
to input a new file path and declare what host this SSH key pair will be used
|
||||
for in your `.ssh/config` file, see [**Working with non-default SSH key pair paths**](#working-with-non-default-ssh-key-pair-paths)
|
||||
for more information.
|
||||
|
||||
1. Once you have input a file path you will be prompted to input a password to
|
||||
|
@ -68,12 +74,12 @@ custom name continue onto the next step.
|
|||
pressing enter.
|
||||
|
||||
>**Note:**
|
||||
If you want to change the password of your key, you can use `ssh-keygen -p <keyname>`.
|
||||
If you want to change the password of your SSH key pair, you can use
|
||||
`ssh-keygen -p <keyname>`.
|
||||
|
||||
1. The next step is to copy the public key as we will need it afterwards.
|
||||
1. The next step is to copy the public SSH key as we will need it afterwards.
|
||||
|
||||
To copy your public key to the clipboard, use the appropriate code for your
|
||||
operating system below:
|
||||
To copy your public SSH key to the clipboard, use the appropriate code below:
|
||||
|
||||
**macOS:**
|
||||
|
||||
|
@ -93,7 +99,7 @@ custom name continue onto the next step.
|
|||
type %userprofile%\.ssh\id_rsa.pub | clip
|
||||
```
|
||||
|
||||
**Windows PowerShell:**
|
||||
**Git Bash on Windows / Windows PowerShell:**
|
||||
|
||||
```bash
|
||||
cat ~/.ssh/id_rsa.pub | clip
|
||||
|
@ -101,22 +107,38 @@ custom name continue onto the next step.
|
|||
|
||||
1. The final step is to add your public SSH key to GitLab.
|
||||
|
||||
Navigate to the 'SSH Keys' tab in you 'Profile Settings'.
|
||||
Navigate to the 'SSH Keys' tab in your 'Profile Settings'.
|
||||
Paste your key in the 'Key' section and give it a relevant 'Title'.
|
||||
Use an identifiable title like 'Work Laptop - Windows 7' or
|
||||
'Home MacBook Pro 15'.
|
||||
|
||||
If you manually copied your public SSH key make sure you copied the entire
|
||||
key starting with `ssh-rsa` and ending with your email.
|
||||
|
||||
1. Optionally you can test your setup by running `ssh -T git@example.com`
|
||||
(replacing `example.com` with your GitLab domain) and verifying that you
|
||||
receive a `Welcome to GitLab` message.
|
||||
|
||||
## Working with non-default SSH key pair paths
|
||||
|
||||
If you used a non-default file path for your GitLab SSH key pair,
|
||||
you must configure your SSH client to find your GitLab SSH private key
|
||||
for connections to your GitLab server (perhaps gitlab.com).
|
||||
you must configure your SSH client to find your GitLab private SSH key
|
||||
for connections to your GitLab server (perhaps `gitlab.com`).
|
||||
|
||||
For OpenSSH clients this is configured in the `~/.ssh/config` file.
|
||||
Below are two example host configurations using their own key:
|
||||
For your current terminal session you can do so using the following commands
|
||||
(replacing `other_id_rsa` with your private SSH key):
|
||||
|
||||
**Git Bash on Windows / GNU/Linux / macOS:**
|
||||
|
||||
```bash
|
||||
eval $(ssh-agent -s)
|
||||
ssh-add ~/.ssh/other_id_rsa
|
||||
```
|
||||
|
||||
To retain these settings you'll need to save them to a configuration file.
|
||||
For OpenSSH clients this is configured in the `~/.ssh/config` file for some
|
||||
operating systems.
|
||||
Below are two example host configurations using their own SSH key:
|
||||
|
||||
```
|
||||
# GitLab.com server
|
||||
|
@ -140,8 +162,8 @@ That's why it needs to uniquely map to a single user.
|
|||
|
||||
## Deploy keys
|
||||
|
||||
Deploy keys allow read-only access to multiple projects with a single SSH
|
||||
key.
|
||||
Deploy keys allow read-only or read-write (if enabled) access to one or
|
||||
multiple projects with a single SSH key pair.
|
||||
|
||||
This is really useful for cloning repositories to your Continuous
|
||||
Integration (CI) server. By using deploy keys, you don't have to setup a
|
||||
|
@ -150,7 +172,8 @@ dummy user account.
|
|||
If you are a project master or owner, you can add a deploy key in the
|
||||
project settings under the section 'Deploy Keys'. Press the 'New Deploy
|
||||
Key' button and upload a public SSH key. After this, the machine that uses
|
||||
the corresponding private key has read-only access to the project.
|
||||
the corresponding private SSH key has read-only or read-write (if enabled)
|
||||
access to the project.
|
||||
|
||||
You can't add the same deploy key twice with the 'New Deploy Key' option.
|
||||
If you want to add the same key to another project, please enable it in the
|
||||
|
@ -166,6 +189,18 @@ project.
|
|||
|
||||
### Eclipse
|
||||
|
||||
How to add your ssh key to Eclipse: https://wiki.eclipse.org/EGit/User_Guide#Eclipse_SSH_Configuration
|
||||
How to add your SSH key to Eclipse: https://wiki.eclipse.org/EGit/User_Guide#Eclipse_SSH_Configuration
|
||||
|
||||
[winputty]: https://the.earth.li/~sgtatham/putty/0.67/htmldoc/Chapter8.html#pubkey-puttygen
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If on Git clone you are prompted for a password like `git@gitlab.com's password:`
|
||||
something is wrong with your SSH setup.
|
||||
|
||||
- Ensure that you generated your SSH key pair correctly and added the public SSH
|
||||
key to your GitLab profile
|
||||
- Try manually registering your private SSH key using `ssh-agent` as documented
|
||||
earlier in this document
|
||||
- Try to debug the connection by running `ssh -Tv git@example.com`
|
||||
(replacing `example.com` with your GitLab domain)
|
||||
|
|
Loading…
Reference in New Issue