Using Personal Access Tokens with GitLab

At time of writing, this “blog” is looking a bit barren. I have the first article, which was written as proof that I could write an article. I have a draft article about tailscale, but it’s nowhere near finished. Even this article right here had a longer version that I abandoned. At this rate of creative output, I’m really wasting the 67p I pay for renewal of the domain each year. Something must be done!

Why I’m doing this

I have a group project. It’s a programming project. As you might imagine, all groups use git to collaborate on the project. We push our commits to a central server, much like I might do to publish this article. That server runs GitLab. I have heard a few people complaining about having to constantly type out their login tokens. I solved this for myself in the first week, but the knowledge is not as common as I thought. We should not have to suffer so.

Step 1 - Get Git

If you’re on Windows, go to this page and click the download link at the top. Run the downloaded program and proceed through the steps as instructed. The default options are fine, with one notable exception. At some point, it will mention “Vim”. You do not want Vim. If the option is available, choose nano instead.

If you’re on Linux, you probably know how to get git. In case you don’t, here’s some options to run in a terminal.

• Arch Linux and derivatives (EndeavourOS, Manjaro, …):

  sudo pacman -S git
  

• Debian and Ubuntu and derivatives (Mint, Raspberry Pi OS, …):

  sudo apt install git
  

• I can’t advise on other distributions because I haven’t used them.

Step 2 - Bash

After this step, things are the same on both platforms. Git for Windows installs an alternative to Command Prompt. It’s called bash. Search for “Git Bash” in your start menu and it should be there. You’ll want to open that.

If you’re on Linux, open a terminal. Your distribution definitely came with one. What it’s called makes no difference. They all behave the same, in essence.

Step 3 - Configuring Git

To avoid typing out your username and token every time, you will need to configure a credential helper. That will store your login information somewhere and retrieve it when git requires. I will be using the simplest helper: git-credential-store, which writes credentials to a file in plain text. That’s not very secure, but it’s no more secure than copying your token from a text file and pasting it into a terminal, which is something I know my associates are doing.

Run this command

git config --global credential.URL.helper store

and substitute URL for the address of the GitLab server, which could be https://gitlab.com, https://projects.[REDACTED].uk, or something else. That’s redacted so you don’t know where I am.

Step 4 - Get your token

Open GitLab in a web browser. Click on your profile icon and go to the preferences page. In the “Access tokens” page, there is a button to add a new token. Remove the expiration date by pressing the X, and be sure to enable “read_repository” and “write_repository”. Once you’ve created the token, don’t close that page. If you close the page before we add the token to your store, there’s no way to get it back.

Step 5 - Add your token

To add a credential to a credential store, you will need to have git prompt you for it. If the login is successful, it will be stored. Go back to your bash terminal and clone, push to, or pull from a repository. Make sure you use the HTTPS URL, not the SSH URL. If a window opens to prompt you, close it. We’re looking for a Username/Password prompt within the terminal. Instead of typing your password, copy the token from GitLab and paste it into the terminal.

Now, you should check to see that everything has worked. Still in the bash terminal, type this command to read the contents of the credential file.

cat ~/.git-credentials

If you are told that there is “No such file or directory”, try steps 3 and 5 again. Otherwise, you should get a response in the form of https://USERNAME:TOKEN@example.com. If you have more than one stored credential, each one will appear on a different line.

Closing comments

Git credentials are just for authenticating with the server, to show that you are allowed to make commits. You will still have to set your git identity for the repository, so that the commits will have your information on them.

git config user.email "git@milkydelta.moe"
git config user.name "milkydelta"

That’s about it. Bye!