====== How do I set up Github authentication on the HPC? ======

Lots of our users need the ability to clone code from https://github.com/, so that they can build software themselves, for their own use.

Most https://github.com/ repositories are in the process of moving over to Git+SSH protocol, rather than the legacy HTTPS access method. In order to commit (or even clone, in many circumstances) you will need an SSH key setting up on our HPC facilities in order to authenticate with Github.

Github.com URL addresses usually look like this:

   * https://github.com/author/project.git
   * git@github.com/author/project.git

To use the __latter__, you need a https://github.com/ account and SSH keys set up. //Sometimes// it is possible to use the former URL, //but not always//, and there is a push to move users over to the git@github.com method.

----

===== Generate SSH Keys =====

On our HPC facility (**Comet** or **Rocket**) run the ''ssh-keygen'' command. You will be prompted to enter the filename where the new SSH keys will be saved. In the example below we enter ''/mnt/nfs/home/USERNAME/.ssh/id_github'':

<code lang=shell-session>
$ ssh-keygen
Generating public/private rsa key pair.
Enter file in which to save the key (/mnt/nfs/home/USERNAME/.ssh/id_rsa): /mnt/nfs/home/USERNAME/.ssh/id_github
Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 
Your identification has been saved in /mnt/nfs/home/USERNAME/.ssh/id_github.
Your public key has been saved in /mnt/nfs/home/USERNAME/.ssh/id_github.pub.
The key fingerprint is:
SHA256:abcdefgh12435788abcdefgWU USERNAME@login.cluster
The key's randomart image is:
+---[RSA 2048]----+
|++=+o.           |
|.*p*.+           |
|..C @ o          |
|+..& B o         |
|*.-.@E= S        |
|.+..o+.          |
|. .+   .         |
|... . .          |
|.   .            |
+----[SHA256]-----+
$
</code>

You should now have two new files created:

   * ''/mnt/nfs/home/USERNAME/.ssh/id_github'' - your **private** key
   * ''/mnt/nfs/home/USERNAME/.ssh/id_github.pub'' -- your **public** key

**Note**: Use your proper University IT account / HPC username instead of the //USERNAME// in the examples above.

----

===== Configure HPC SSH Settings =====

On our HPC facilities (**Comet** or **Rocket**), run the following command to open your personal SSH config file in a text editor:

<code lang=shell-session>
$ nano $HOME/.ssh/config
</code>

At the top of the opened file, add in the following text:

<code>
IdentitiesOnly yes

Host github.com
  Hostname github.com
  User git
  IdentityFile /mnt/nfs/home/USERNAME/.ssh/id_github
</code>

Ensuring that you change //USERNAME// to be your correct University IT account / HPC username. Then save the file and exit ''nano''.

At this point, when you attempt to use the ''git'' commands on our HPC facilities with any repository on Github.com which uses a //git@github.com// URL, your **private** key will be loaded automatically.

----

===== Configure Github.com SSH Settings =====

You now need to notify https://Github.com/ to accept the SSH public key you generated. Take a copy of the contents of ''id_github.pub'' (either use scp to copy the file off the HPC, or just copy the contents of the file in your SSH session; it is just alphanumeric text).

<WRAP box round important>
**Be Careful!**

Do __not__ use ''id_github''. This is your __private__ key and should **never** be shared with anyone. Only paste the content of your __public__ key; ''id_github.pub''.
</WRAP>

   * Log in to https://github.com/ and create an account, if you do not already have one.

   * Once signed in, navigate to your [[https://github.com/settings/profile|user settings]] page

   * On the settings menu select the [[https://github.com/settings/keys|SSH and GPG keys]] menu item under //Access//:

{{:faq:github_ssh_menu.png?300|}}

   * On the SSH & GPG Keys page which loads, click the '**New SSH Key**' button:

{{:faq:github_ssh_add.png?750|}}

   * A form will load, prompting for a **Key Title** and **Key** contents:

{{:faq:github_ssh_save.png?750|}}

   * Paste the contents of your ''id_github.pub'' file from the HPC system into the **Key** box, double-check that the **Key Type** is set to //Authentication// and press the **Add Key** button to save. You can use any title you want.

You can now use the ''git'' command on the HPC system using the SSH config you prepared earlier. All //git@github.com// URL addresses should work.

=== Check your Setup ===

You can check your keys are working against Github using the following command:

<code lang=shell-session>
$ ssh -T git@github.com
</code>

The first attempt will produce a message:

<code lang=shell-session>
The authenticity of host 'github.com (192.30.255.112)' can't be established.
RSA key fingerprint is SHA256:nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/[fingerprint])? y
Please type 'yes', 'no' or the fingerprint: yes
Warning: Permanently added 'github.com' (RSA) to the list of known hosts.
</code>

At this point you are all done!

**Note**: If you see an error like the one below, your key setup is incorrect:

<code lang=shell-session>
git@github.com: Permission denied (publickey).
</code>

Re-read the instructions above to re-do the setup, including setting up your keys with ''ssh-keygen'', checking your ''$HOME/.ssh/config'' and verifying your [[https://github.com/settings/keys|Github.com SSH & GPG Keys]] settings.

----

[[:faq:index|Back to FAQ]]