Use a personal access token to access GitLab using SourceTree

Use a personal access token to access GitLab using SourceTree

Back in August 2018, the SourceTree blog announced that version 3.0 introduced support for a number of different Git hosts based on growing customer demand. One of the most requested hosts was GitLab.com.

This tutorial shows you how to set up SourceTree with GitLab.com using a personal access token.

This option is excellent if you want to access your GitLab.com repositories on your work and personal PC and don’t want to bother managing SSH keys across PCs.

If your GitLab.com account uses Two-factor Authentication (2FA) you must use a personal access token as your password to clone repositories over HTTPS to your local PC environment.

Before you start

This tutorial was written in April 2021 using a MacBook Pro running macOS Big Sur. The procedures for adding an account to SourceTree should apply equally to Windows 10 users, however the procedure has not been tested or verified on this operating system.

Gather the following accounts and other information.

  • An account on GitLab.com

  • Your GitLab.com username. You can find this in your user profile below your name.

    Screenshot of the GitLab Account Settings menu open with the username highlighted

  • SourceTree installed with your Atlassian account connected and verified.

Create a personal access token in GitLab

To connect SourceTree with GitLab.com, you can either use SSH or create a personal access token. Personal access tokens let you authenticate with GitLab over HTTPS with 2FA.

To create a personal access token:

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

  2. In the side bar, click Access Tokens to load the Personal Access Tokens screen.

  3. Add a personal access token by completing the following fields:

    Name

    Add a short descriptive name for your token. For example, SourceTree Desktop.

    Expires at

    Leave the date field blank so the token never expires. Or if you prefer, select an expiry date you feel comfortable with.

    Scopes

    Select the api and read_user scopes for your token. This allows SourceTree to have full read and write permissions to your repositories and lets the app access your user account settings so it can add this information to commits.

    Your screen should look like this example.

    Screenshot of GitLab personal access token settings with api and read user scopes selected

  4. Click Create personal access token.

  5. Save the personal access token to a safe place (a secure password manager is recommmended).

    Screenshot of the created token
    This step is the last time you will have access to the personal access token. Make sure you save it now before continuing.

Configure the SourceTree GitLab.com account profile

Now you have created and saved the personal access token, you can configure SourceTree with this token and access your GitLab.com repositories.

To set up a GitLab.com 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

    Paste your personal access token into the field.

    Protocol

    Select HTTPS from the list.

  4. Click Save.

  5. Close the Accounts screen.

Test the GitLab account by cloning a GitLab repository

To clone repositories from the GitLab.com remote host:

  1. In SourceTree, click the Remote option.

  2. Expand the GitLab group.

  3. Click the Clone link for the repository you want to clone.

  4. Check that the Clone a repository modal displays the https:// prefix in the Source URL field.

    Screenshot of the clone repository modal showing https protocol

  5. Click Clone to clone the selected repository to your local environment.

Summary

You have configured a GitLab.com account in SourceTree that uses a personal access token to authenticate with GitLab.com

comments powered by Disqus