Use a SSH key to access GitLab through SourceTree

Use a SSH key to access GitLab through SourceTree

If you want to make the switch to GitLab.com from GitHub, or BitBucket Cloud or Server, you can use SourceTree 3.0 to manage your repositories on your local system.

SourceTree offers two ways of connnecting your GitLab.com account to SourceTree:

Overview

The basic process to follow is outlined below:

  • Retrieve or generate your SSH Public Key.

  • Apply the public key to your GitLab user profile.

  • Add a GitLab.com Account profile to SourceTree using the SSH protocol.

Read on for step-by-step instructions.

Managing your SSH keys

GitLab supports SSH as a method to handle authentication between local and remote repositories. The advantage of SSH is that you do not need to provide a User Name or Password when you commit work.

To push content to GitLab using SourceTree, you will need to generate a SSH Public Key using the command-line on your Windows, Mac, or Linux PC.

Before you go any further, SourceTree 3.0 can manage this process for you.

When you add a GitLab.com account to SourceTree you can hold down the Alt (Windows) or Option (macOS) keys to switch the Copy to clipboard button to the Generate key function. SourceTree will guide you through the process of generating a key and manage the entire process for you in the app.

If you prefer to manage your SSH keys outside of SourceTree, the following procedures and references will help you achieve this.

Retrieve an existing public key

The SSH protocol handles all aspects of verifying who you are using Public Key Cryptography. It is a very secure method of authentication, which is why many folks choose it as the only way they interact with GitLab, and other Version Control Systems (VCS).

If you have set up SSH for GitHub or another repository before, you can run either of these commands in a terminal to retrieve your public key:

Windows

type %userprofile%\.ssh\id_rsa.pub

Mac or Linux

cat ~/.ssh/id_rsa.pub

If either of these commands returns a public key, you can jump to Apply the key pair to your user profile and continue with the tutorial.

If you don’t get any keys returned, continue to the next section.

Generate a SSH key pair

If you do not get a key after issuing either of these commands, read on for instructions.

To create a SSH Key Pair:

  1. Load https://gitlab.com/help/ssh/README#generate-an-ssh-key-pair in your browser.

  2. Read the instructions described on this page, and use the commands specified to generate the required key pair.

Apply the key pair to your user profile

To apply the key to your profile:

  1. Load https://gitlab.com/-/profile/preferences to access your user profile settings page.

  2. In the side bar, click SSH Keys.

  3. Paste the key into the Key field.

  4. Set a descriptive name for the key in the Title field.

  5. Leave the Expires at date blank if you want the key to never expire.

  6. Click Add key to set the SSH key.

Configure the SourceTree GitLab.com SSH account profile

Now you have created and saved the SSH key to your GitLab.com profile, you can set up a SourceTree GitLab account profile to connect through SSH.

To set up a GitLab.com SSH account profile in SourceTree:

  1. Open the SourceTree  Preferences  Accounts screen.

  2. Click Add…​ to open the account options screen.

  3. Set the following options:

    Host

    Select GitLab.com from the list.

    Username

    Type your username (not your email) into the field.

    Password

    Type your password into the filed.

    If you are using Two-factor Authentication on your GitLab.com account, read my April 2021 blog post about SourceTree and GitLab.com for help with creating a personal access token.
    Protocol

    Select SSH from the list.

  4. Click Save.

  5. Close the Accounts screen.

The repository is cloned using the SSH protocol and now appears in the Local tab of SourceTree.

Bonus: Update local legacy repositories to point To GitLab repositories in SourceTree

If you are migrating all your repositories over from another VCS to GitLab, chances are you have all the old repositories checked-out locally already.

You don’t need to delete them all and check them out again through GitLab. Update the remote origin to point to the new GitLab SSH path and you can continue seamlessly.

Make sure all your work is pushed to your remote repositories before doing this part of the tutorial.

To change remote repository information in SourceTree:

  1. Load https://gitlab.com in your browser.

  2. Navigate to the GitLab repository you want to update locally.

  3. Copy the SSH path shown in the screen.

    The SSH path should be the default. If HTTPS is shown, change it to SSH to refresh the URL.

  4. Open SourceTree.

  5. Click the Local tab to display all locally-tracked repositories.

  6. Double-click on a repository to open the interface for the selected repository.

  7. Click Settings (top right of the interface).

  8. In the Remotes group, click on the origin path, and then click Edit.

  9. Paste the SSH path you copied from the GitLab UI into this field and then click Save.

  10. Click Fetch to retrieve the remote configuration and update the Remotes group settings.

comments powered by Disqus