What you will need

What you will get

  • GitHub correctly configured on your computer

GitHub and Git LFS installation#

If you have followed this manual in order, Git and Git Large File System (LFS) have already been installed during : Software dependencies installation.

Since repetita iuvant, try again:

sudo apt update
sudo apt install git git-lfs git-extras

GitHub setup#

Setting up global configurations for Git#

Use these commands to tell Git who you are:

git config --global user.email "![email]"
git config --global user.name  "![full name]"

Connect with SSH#

To seamlessly access GitHub through terminal without having to enter the password each time, you can establish an SSH key and adding it to the GitHub SSH agent.

Follow the SSH instructions on GitHub, or continue reading below.

Checking for existing SSH keys#

First, check if you already have existing GitHub SSH keys on your computer:

Before you generate a new SSH key, you should check your local machine for existing keys.

  1. Open Terminal.

  2. Enter ls -al ~/.ssh to see if existing SSH keys are present.

    $ ls -al ~/.ssh
# Lists the files in your .ssh directory, if they exist

  3. Check the directory listing to see if you already have a public SSH key. By default, the filenames of supported public keys for GitHub are one of the following.

    • id_rsa.pub

    • id_ecdsa.pub

    • id_ed25519.pub

    Tip

    If you receive an error that ~/.ssh doesn’t exist, you do not have an existing SSH key pair in the default location. You can create a new SSH key pair in the next step.

  4. Either generate a new SSH key or upload an existing key.

    • If you don’t have a supported public and private key pair, or don’t wish to use any that are available, generate a new SSH key.

    • If you see an existing public and private key pair listed (for example, id_rsa.pub and id_rsa) that you would like to use to connect to GitHub, you can add the key to the ssh-agent.

Before you generate a new SSH key, you should check your local machine for existing keys.

  1. Open Terminal.

  2. Enter ls -al ~/.ssh to see if existing SSH keys are present.

    $ ls -al ~/.ssh
# Lists the files in your .ssh directory, if they exist

  3. Check the directory listing to see if you already have a public SSH key. By default, the filenames of supported public keys for GitHub are one of the following.

    • id_rsa.pub

    • id_ecdsa.pub

    • id_ed25519.pub

    Tip

    If you receive an error that ~/.ssh doesn’t exist, you do not have an existing SSH key pair in the default location. You can create a new SSH key pair in the next step.

  4. Either generate a new SSH key or upload an existing key.

    • If you don’t have a supported public and private key pair, or don’t wish to use any that are available, generate a new SSH key.

    • If you see an existing public and private key pair listed (for example, id_rsa.pub and id_rsa) that you would like to use to connect to GitHub, you can add the key to the ssh-agent.

Before you generate a new SSH key, you should check your local machine for existing keys.

  1. Open Git Bash.

  2. Enter ls -al ~/.ssh to see if existing SSH keys are present.

    $ ls -al ~/.ssh
# Lists the files in your .ssh directory, if they exist

  3. Check the directory listing to see if you already have a public SSH key. By default, the filenames of supported public keys for GitHub are one of the following.

    • id_rsa.pub

    • id_ecdsa.pub

    • id_ed25519.pub

    Tip

    If you receive an error that ~/.ssh doesn’t exist, you do not have an existing SSH key pair in the default location. You can create a new SSH key pair in the next step.

  4. Either generate a new SSH key or upload an existing key.

    • If you don’t have a supported public and private key pair, or don’t wish to use any that are available, generate a new SSH key.

    • If you see an existing public and private key pair listed (for example, id_rsa.pub and id_rsa) that you would like to use to connect to GitHub, you can add the key to the ssh-agent.

Generating a new SSH key#

From GitHub:

You can generate a new SSH key on your local machine. After you generate the key, you can add the public key to your account on GitHub.com to enable authentication for Git operations over SSH.

  1. Open Terminal.

  2. Paste the text below, replacing the email used in the example with your GitHub email address.

    ssh-keygen -t ed25519 -C "[email protected]"

    Note

    If you are using a legacy system that doesn’t support the Ed25519 algorithm, use:

    ssh-keygen -t rsa -b 4096 -C "[email protected]"

    This creates a new SSH key, using the provided email as a label.

    > Generating public/private ALGORITHM key pair.

    When you’re prompted to “Enter a file in which to save the key”, you can press Enter to accept the default file location. Please note that if you created SSH keys previously, ssh-keygen may ask you to rewrite another key, in which case we recommend creating a custom-named SSH key. To do so, type the default file location and replace id_ALGORITHM with your custom key name.

    > Enter a file in which to save the key (/home/YOU/.ssh/id_ALGORITHM):[Press enter]

  3. At the prompt, type a secure passphrase.

    > Enter passphrase (empty for no passphrase): [Type a passphrase]
> Enter same passphrase again: [Type passphrase again]

You can generate a new SSH key on your local machine. After you generate the key, you can add the public key to your account on GitHub.com to enable authentication for Git operations over SSH.

  1. Open Terminal.

  2. Paste the text below, replacing the email used in the example with your GitHub email address.

    ssh-keygen -t ed25519 -C "[email protected]"

    Note

    If you are using a legacy system that doesn’t support the Ed25519 algorithm, use:

    ssh-keygen -t rsa -b 4096 -C "[email protected]"

    This creates a new SSH key, using the provided email as a label.

    > Generating public/private ALGORITHM key pair.

    When you’re prompted to “Enter a file in which to save the key”, you can press Enter to accept the default file location. Please note that if you created SSH keys previously, ssh-keygen may ask you to rewrite another key, in which case we recommend creating a custom-named SSH key. To do so, type the default file location and replace id_ALGORITHM with your custom key name.

    > Enter a file in which to save the key (/Users/YOU/.ssh/id_ALGORITHM):[Press enter]

  3. At the prompt, type a secure passphrase.

    > Enter passphrase (empty for no passphrase): [Type a passphrase]
> Enter same passphrase again: [Type passphrase again]

You can generate a new SSH key on your local machine. After you generate the key, you can add the public key to your account on GitHub.com to enable authentication for Git operations over SSH.

  1. Open Git Bash.

  2. Paste the text below, replacing the email used in the example with your GitHub email address.

    ssh-keygen -t ed25519 -C "[email protected]"

    Note

    If you are using a legacy system that doesn’t support the Ed25519 algorithm, use:

    ssh-keygen -t rsa -b 4096 -C "[email protected]"

    This creates a new SSH key, using the provided email as a label.

    > Generating public/private ALGORITHM key pair.

    When you’re prompted to “Enter a file in which to save the key”, you can press Enter to accept the default file location. Please note that if you created SSH keys previously, ssh-keygen may ask you to rewrite another key, in which case we recommend creating a custom-named SSH key. To do so, type the default file location and replace id_ALGORITHM with your custom key name.

    > Enter file in which to save the key (c:\Users\YOU\.ssh\id_ALGORITHM):[Press enter]

  3. At the prompt, type a secure passphrase.

    > Enter passphrase (empty for no passphrase): [Type a passphrase]
> Enter same passphrase again: [Type passphrase again]

Adding your SSH key to the SSH agent#

From GitHub:

Before adding a new SSH key to the ssh-agent to manage your keys, you should have checked for existing SSH keys and generated a new SSH key.

  1. Start the ssh-agent in the background.

    $ eval "$(ssh-agent -s)"
> Agent pid 59566

    Depending on your environment, you may need to use a different command. For example, you may need to use root access by running sudo -s -H before starting the ssh-agent, or you may need to use exec ssh-agent bash or exec ssh-agent zsh to run the ssh-agent.

  2. Add your SSH private key to the ssh-agent.

    If you created your key with a different name, or if you are adding an existing key that has a different name, replace id_ed25519 in the command with the name of your private key file.

    ssh-add ~/.ssh/id_ed25519

  3. Add the SSH public key to your account on GitHub.

Before adding a new SSH key to the ssh-agent to manage your keys, you should have checked for existing SSH keys and generated a new SSH key. When adding your SSH key to the agent, use the default macOS ssh-add command, and not an application installed by macports, homebrew, or some other external source.

  1. Start the ssh-agent in the background.

    $ eval "$(ssh-agent -s)"
> Agent pid 59566

    Depending on your environment, you may need to use a different command. For example, you may need to use root access by running sudo -s -H before starting the ssh-agent, or you may need to use exec ssh-agent bash or exec ssh-agent zsh to run the ssh-agent.

  2. If you’re using macOS Sierra 10.12.2 or later, you will need to modify your ~/.ssh/config file to automatically load keys into the ssh-agent and store passphrases in your keychain.

    • First, check to see if your ~/.ssh/config file exists in the default location.

    $ open ~/.ssh/config
> The file /Users/YOU/.ssh/config does not exist.

    • If the file doesn’t exist, create the file.

    touch ~/.ssh/config

    • Open your ~/.ssh/config file, then modify the file to contain the following lines. If your SSH key file has a different name or path than the example code, modify the filename or path to match your current setup.

    Host github.com
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519

    Note

    • If you chose not to add a passphrase to your key, you should omit the UseKeychain line.

    • If you see a Bad configuration option: usekeychain error, add an additional line to the configuration’s’ Host *.github.com section.

    Host github.com
  IgnoreUnknown UseKeychain

  3. Add your SSH private key to the ssh-agent and store your passphrase in the keychain. If you created your key with a different name, or if you are adding an existing key that has a different name, replace id_ed25519 in the command with the name of your private key file.

    ssh-add --apple-use-keychain ~/.ssh/id_ed25519

    Note

    The --apple-use-keychain option stores the passphrase in your keychain for you when you add an SSH key to the ssh-agent. If you chose not to add a passphrase to your key, run the command without the --apple-use-keychain option.

    The --apple-use-keychain option is in Apple’s standard version of ssh-add. In macOS versions prior to Monterey (12.0), the --apple-use-keychain and --apple-load-keychain flags used the syntax -K and -A, respectively.

    If you don’t have Apple’s standard version of ssh-add installed, you may receive an error.

    If you continue to be prompted for your passphrase, you may need to add the command to your ~/.zshrc file (or your ~/.bashrc file for bash).

  4. Add the SSH public key to your account on GitHub.

Before adding a new SSH key to the ssh-agent to manage your keys, you should have checked for existing SSH keys and generated a new SSH key.

If you have GitHub Desktop installed, you can use it to clone repositories and not deal with SSH keys.

  1. In a new admin elevated PowerShell window, ensure the ssh-agent is running.

    # start the ssh-agent in the background
Get-Service -Name ssh-agent | Set-Service -StartupType Manual
Start-Service ssh-agent

  2. In a terminal window without elevated permissions, add your SSH private key to the ssh-agent. If you created your key with a different name, or if you are adding an existing key that has a different name, replace id_ed25519 in the command with the name of your private key file.

    ssh-add c:\Users\YOU\.ssh\id_ed25519

  3. Add the SSH public key to your account on GitHub.

Generating a new SSH key for a hardware security key#

If you want to step up your security, you can set up a hardware security key. From GitHub:

If you are using macOS or Linux, you may need to update your SSH client or install a new SSH client prior to generating a new SSH key.

  1. Insert your hardware security key into your computer.

  2. Open Terminal.

  3. Paste the text below, replacing the email address in the example with the email address associated with your account on GitHub.

    ssh-keygen -t ed25519-sk -C "[email protected]"

    Note

    If the command fails and you receive the error invalid format or feature not supported, you may be using a hardware security key that does not support the Ed25519 algorithm. Enter the following command instead.

    ssh-keygen -t ecdsa-sk -C "[email protected]"

  4. When you are prompted, touch the button on your hardware security key.

  5. When you are prompted to “Enter a file in which to save the key,” press Enter to accept the default file location.

    > Enter a file in which to save the key (/Users/YOU/.ssh/id_ed25519_sk):[Press enter]

  6. When you are prompted to type a passphrase, press Enter.

    > Enter passphrase (empty for no passphrase): [Type a passphrase]
> Enter same passphrase again: [Type passphrase again]

  7. Add the SSH public key to your account on GitHub.

If you are using macOS or Linux, you may need to update your SSH client or install a new SSH client prior to generating a new SSH key.

  1. Insert your hardware security key into your computer.

  2. Open Terminal.

  3. Paste the text below, replacing the email address in the example with the email address associated with your account on GitHub.

    ssh-keygen -t ed25519-sk -C "[email protected]"

    Note

    If the command fails and you receive the error invalid format or feature not supported, you may be using a hardware security key that does not support the Ed25519 algorithm. Enter the following command instead.

    ssh-keygen -t ecdsa-sk -C "[email protected]"

  4. When you are prompted, touch the button on your hardware security key.

  5. When you are prompted to “Enter a file in which to save the key,” press Enter to accept the default file location.

    > Enter a file in which to save the key (/Users/YOU/.ssh/id_ed25519_sk):[Press enter]

  6. When you are prompted to type a passphrase, press Enter.

    > Enter passphrase (empty for no passphrase): [Type a passphrase]
> Enter same passphrase again: [Type passphrase again]

  7. Add the SSH public key to your account on GitHub.

If you are using macOS or Linux, you may need to update your SSH client or install a new SSH client prior to generating a new SSH key.

  1. Insert your hardware security key into your computer.

  2. Open Git Bash.

  3. Paste the text below, replacing the email address in the example with the email address associated with your account on GitHub.

    ssh-keygen -t ed25519-sk -C "[email protected]"

    Note

    If the command fails and you receive the error invalid format or feature not supported, you may be using a hardware security key that does not support the Ed25519 algorithm. Enter the following command instead.

    ssh-keygen -t ecdsa-sk -C "[email protected]"

  4. When you are prompted, touch the button on your hardware security key.

  5. When you are prompted to “Enter a file in which to save the key,” press Enter to accept the default file location.

    > Enter a file in which to save the key (c:\Users\YOU\.ssh\id_ed25519_sk):[Press enter]

  6. When you are prompted to type a passphrase, press Enter.

    > Enter passphrase (empty for no passphrase): [Type a passphrase]
> Enter same passphrase again: [Type passphrase again]

  7. Add the SSH public key to your account on GitHub.

Adding a new SSH key to your GitHub account#

From GitHub:

You can add an SSH key and use it for authentication, or commit signing, or both. If you want to use the same SSH key for both authentication and signing, you need to upload it twice.

After adding a new SSH authentication key to your account on GitHub.com, you can reconfigure any local repositories to use SSH.

  1. Copy the SSH public key to your clipboard.

    If your SSH public key file has a different name than the example code, modify the filename to match your current setup. When copying your key, don’t add any newlines or whitespace.

    $ cat ~/.ssh/id_ed25519.pub
# Then select and copy the contents of the id_ed25519.pub file
# displayed in the terminal to your clipboard

    Tip

    Alternatively, you can locate the hidden .ssh folder, open the file in your favorite text editor, and copy it to your clipboard.

  2. In the upper-right corner of any page on GitHub, click your profile photo, then click Settings.

  3. In the “Access” section of the sidebar, click SSH and GPG keys.

  4. Click New SSH key or Add SSH key.

  5. In the “Title” field, add a descriptive label for the new key. For example, if you’re using a personal laptop, you might call this key “Personal laptop”.

  6. Select the type of key, either authentication or signing.

  7. In the “Key” field, paste your public key.

  8. Click Add SSH key.

  9. If prompted, confirm access to your account on GitHub.

You can add an SSH key and use it for authentication, or commit signing, or both. If you want to use the same SSH key for both authentication and signing, you need to upload it twice.

After adding a new SSH authentication key to your account on GitHub.com, you can reconfigure any local repositories to use SSH.

  1. Copy the SSH public key to your clipboard.

    If your SSH public key file has a different name than the example code, modify the filename to match your current setup. When copying your key, don’t add any newlines or whitespace.

    $ pbcopy < ~/.ssh/id_ed25519.pub
# Copies the contents of the id_ed25519.pub file to your clipboard

    Tip

    If pbcopy isn’t working, you can locate the hidden .ssh folder, open the file in your favorite text editor, and copy it to your clipboard.

  2. In the upper-right corner of any page on GitHub, click your profile photo, then click Settings.

  3. In the “Access” section of the sidebar, click SSH and GPG keys.

  4. Click New SSH key or Add SSH key.

  5. In the “Title” field, add a descriptive label for the new key. For example, if you’re using a personal laptop, you might call this key “Personal laptop”.

  6. Select the type of key, either authentication or signing.

  7. In the “Key” field, paste your public key.

  8. Click Add SSH key.

  9. If prompted, confirm access to your account on GitHub.

You can add an SSH key and use it for authentication, or commit signing, or both. If you want to use the same SSH key for both authentication and signing, you need to upload it twice.

After adding a new SSH authentication key to your account on GitHub.com, you can reconfigure any local repositories to use SSH.

  1. Copy the SSH public key to your clipboard.

    If your SSH public key file has a different name than the example code, modify the filename to match your current setup. When copying your key, don’t add any newlines or whitespace.

    $ clip < ~/.ssh/id_ed25519.pub
# Copies the contents of the id_ed25519.pub file to your clipboard

    Note

    • With Windows Subsystem for Linux (WSL), you can use clip.exe. Otherwise if clip isn’t working, you can locate the hidden .ssh folder, open the file in your favorite text editor, and copy it to your clipboard.

    • On newer versions of Windows that use the Windows Terminal, or anywhere else that uses the PowerShell command line, you may receive a ParseError stating that The '&lt;' operator is reserved for future use. In this case, the following alternative clip command should be used:

    $ cat ~/.ssh/id_ed25519.pub | clip
# Copies the contents of the id_ed25519.pub file to your clipboard

  2. In the upper-right corner of any page on GitHub, click your profile photo, then click Settings.

  3. In the “Access” section of the sidebar, click SSH and GPG keys.

  4. Click New SSH key or Add SSH key.

  5. In the “Title” field, add a descriptive label for the new key. For example, if you’re using a personal laptop, you might call this key “Personal laptop”.

  6. Select the type of key, either authentication or signing.

  7. In the “Key” field, paste your public key.

  8. Click Add SSH key.

  9. If prompted, confirm access to your account on GitHub.

Testing your SSH connection#

From GitHub:

  1. Open Terminal.

  2. Enter the following:

    ssh -T git@github.com
# Attempts to ssh to GitHub

    You may see a warning like this:

    > The authenticity of host 'github.com (IP ADDRESS)' can't be established.
> ED25519 key fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU.
> Are you sure you want to continue connecting (yes/no)?

  3. Verify that the fingerprint in the message you see matches GitHub’s public key fingerprint. If it does, then type yes:

    > Hi USERNAME! You've successfully authenticated, but GitHub does not
> provide shell access.

    You may see this error message:

    ...
Agent admitted failure to sign using the key.
debug1: No more authentication methods to try.
Permission denied (publickey).

    This is a known problem with certain Linux distributions.

    Note

    The remote command should exit with code 1.

  4. Verify that the resulting message contains your username.

  1. Open Terminal.

  2. Enter the following:

    ssh -T git@github.com
# Attempts to ssh to GitHub

    You may see a warning like this:

    > The authenticity of host 'github.com (IP ADDRESS)' can't be established.
> ED25519 key fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU.
> Are you sure you want to continue connecting (yes/no)?

  3. Verify that the fingerprint in the message you see matches GitHub’s public key fingerprint. If it does, then type yes:

    > Hi USERNAME! You've successfully authenticated, but GitHub does not
> provide shell access.

    Note

    The remote command should exit with code 1.

  4. Verify that the resulting message contains your username.

  1. Open Git Bash.

  2. Enter the following:

    ssh -T git@github.com
# Attempts to ssh to GitHub

    You may see a warning like this:

    > The authenticity of host 'github.com (IP ADDRESS)' can't be established.
> ED25519 key fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU.
> Are you sure you want to continue connecting (yes/no)?

  3. Verify that the fingerprint in the message you see matches GitHub’s public key fingerprint. If it does, then type yes:

    > Hi USERNAME! You've successfully authenticated, but GitHub does not
> provide shell access.

    Note

    The remote command should exit with code 1.

  4. Verify that the resulting message contains your username.

See also

If you have never heard of Git or GitHub before, you can do some background reading here:

You can then go through the Duckietown introduction to version control with Git.