index

glab at university

This blog post is specifically aimed at fellow CS students at Umeå University trying to setup the GitLab CLI without tripping, but should be applicable for others as well.

The GitLab CLI, called glab, is a CLI program which enables you to interact with your GitLab projects right from the terminal, just like gh is for github.com.

Common uses include:

  • Cloning repositories easily with glab repo clone username/repository
  • Creating new repositories with glab repo create. The command also allows for quickly syncing up an existing local repository, just by running this command in the local repository folder.
  • Creating, viewing and closing issues with commands such as glab issue create.
  • Having glab authenticate git for you, so you do not have to use an SSH key. For some, SSH keys are simpler, so this is an individual choice.

For a full list of commands, just run glab --help or glab repo --help, etc.

If you want to learn how to configure git, you probably want to do that with SSH keys as a beginner. This post is about glab, a complementary tool when you already know your up from down with git.

The CS institution at Umeå University gives us access to a GitLab server at https://git.cs.umu.se/. It is a self-hosted instance of GitLab, which just means that the CS institution is hosting GitLab’s software on a server in the deep bowels of the, uh, university.

To setup glab, we will follow these step:

  1. Basic prerequisites.
  2. Install the GitLab CLI so we can run glab in the terminal.
  3. Configure the GITLAB_HOST environment variable, to make sure glab is always talking to git.cs.umu.se and not gitlab.com.
  4. Create an access token.
  5. Login with the access token.
  6. (OPTIONAL) Configure git to authenticate using glab

0. Preqrequisites

Required programs:

  • A file editor - eg. vscode, notepad or even vim
  • git must be installed

The instructions will require you to open files using a code editor. The provided instructions will instruct you to open the files using Visual Studio Code.

0. a) MacOS specific prerequisites

Package manager

Homebrew must be installed and available in the terminal. Make sure that when running the command:

brew

it does not say “command not found”. Ignoring the advertisement for Warp, This tutorial explains it well.

Opening files using vscode

Opening files from the terminal using vscode on MacOS requires you to install the code command:

  1. Open vscode

  2. Open the command palette with View>Command palette, or press ⌘ + ⇧ + P

  3. and then write and select
    Shell Command: Install 'code' command in PATH

1. Installation

We will be installing the GitLab CLI so we can run glab in the terminal.

1. a) Install glab on Windows

We will be installing glab using WinGet, Microsoft’s package manager on Windows.

In a PowerShell terminal, run:

winget install GLab.GLab

“Windows PowerShell” is the old shell, “Powershell” is the new one. I recommend installing the new one and hiding the old one in your Windows Terminal profile list, but that is a separate topic.

1. b) Install glab on MacOS

We will be using the package manager Homebrew. If you are a up-and-coming developer on Mac and have not yet used brew to install developer tools, you should try it. Make sure to first install the package manager and then run:

brew install glab

1. c) Install glab on Linux

If you are on the institutions computers you can’t install stuff, so I’m assuming you are using Linux on your own computer, either as your main OS or dual-booted beside Windows or virtualized using WSL on top of Windows.

Ubuntu

snap install glab

Fedora

dnf install glab

Literally any other distro

For all other distros I recommend checking the official install instructions.

2. Configure the GITLAB_HOST environment variable

We are going to force glab to only speak to git.cs.umu.se and not gitlab.com by setting the GITLAB_HOST environment variable. This is just a variable for your shell environment that glab looks for.

If you normally use gitlab.com for personal projects, then you don’t set this variable.

If you do not set this variable, when running glab repo clone username/repository it will just give you back an “Unathorized” error, since it tries communicating with gitlab.com which, of course, we’re not logged in to.

2. a) Configuring glab on Windows

  1. Open your PowerShell Profile from a PowerShell terminal. If you have vscode installed, just run:
   code $PROFILE

And if you don’t have vscode, run:

notepad $PROFILE

  1. Add the line:

    $env:GITLAB_HOST = "git.cs.umu.se"

  2. Restart your terminal

2. b) Configuring glab on macOS

These instructions assume that you are using the default shell which, for macOS versions after 2019, is zsh.

You can check which shell you are using by running echo $SHELL. If it says that you are using bash, then you need to edit your ~/.bashrc file instead.

Open the ~/.zshrc file. This can be done from the terminal using eg. vscode by running code ~/.zshrc.

To your ~/.zshrc file, add the line:

export GITLAB_HOST="git.cs.umu.se"

The tilde character, ~, is a shorthand for your home folder, which on Mac is /Users/yourusername.

Verify that it works by running echo $GITLAB_HOST in a completely new terminal, it should say git.cs.umu.se.

2. c) Configuring glab on Linux

I am assuming that you are using bash as your shell, if you do not know what a shell is, then you are using bash.

[!definition] Other shells If you are not using bash, then you will set the GITLAB_HOST environment variable in the appropriate way for your shell.

3. Get an access token

A Personal Access Token (PAT for short), is a sensitive text string which allows anyone who get a hold of it to access https://git.cs.umu.se/ as you. Protect it with care.

  1. Go to https://git.cs.umu.se/
  2. Click on your profile picture
  3. Click on Preferences
  4. Click on Personal access tokens
  5. Click on Add new token
  6. Name your token something which explains what it is for, e.g. “GitLab CLI”
  7. Make sure at least the permissions glab requests (api and write_repository) are selected.
  8. Select an appropriate expiration date, the limit at the time of writing is one year from today.
  9. Copy the token you created.
  10. Optionally save the token in your password manager of choice: Bitwarden, 1password etc.

You will need to create a new token when this one expires.

4. Login with glab on the terminal

Run the command

glab auth login

which will start an interactive wizard. Use the arrow keys to go up and down and press Enter to confirm.

  1. Make sure git.cs.umu.se is the GitLab instance you are logging into.

If it only gives you the option between gitlab.com and “self-hosted instance”, choose self-hosted instance and write git.cs.umu.se. Use the default API host by clicking Enter if it asks for it.

  1. Make sure to select Token when it asks you how to login.
  2. Paste the access token you created earlier
  3. For git protocol, if you use an SSH key to authenticate git, then select SSH, otherwise choose HTTPS.
  4. If you selected HTTPS, answer yes (y), when it comes to authenticating git with your GitLab credentials.

If you are interested in knowing what I do, then I will tell you that I personally use HTTPS for authenticating git to GitHub and GitLab, along with using GPG keys for signing all my commits.

5. (OPTIONAL) Configure git to use glab to login

If you are using HTTPS authentication and selected on step 4 above, this will be done for you.

Open your global git config by running:

code ~/.gitconfig

Edit the file so it is similar to the following example, and make sure to replace Your Full Name Here and yourcsusername with the correct information:

[user]
name = Your full name here
email = [email protected]

[credential "https://git.cs.umu.se"]
   helper = "!glab auth git-credential"

Verify that you are logged in

When running:

glab auth status

it should be green checkmarks on everything under git.cs.umu.se:

git.cs.umu.se
  ✓ Logged in to git.cs.umu.se as bob (/home/bob/.config/glab-cli/config.yml)
  ✓ Git operations for git.cs.umu.se configured to use https protocol.
  ✓ API calls for git.cs.umu.se are made over https protocol.
  ✓ REST API Endpoint: https://git.cs.umu.se/api/v4/
  ✓ GraphQL Endpoint: https://git.cs.umu.se/api/graphql/
  ✓ Token found: **************************

If you have any projects on https://git.cs.umu.se/, they should now show up if you run:

glab repo list

After doing all this, make sure to restart IntelliJ, vscode and terminals. If IntelliJ for example still want asks for username and password, try running git fetch through the terminal once in your repository.

Closing remarks

While these tools aren’t necessary or vital in any way, if you followed along some or all of the steps above, you have practiced configuring your own system.

You are the master of your own machine.