Awesome

lab interacts with repositories on GitLab, including creating/editing merge requests, issues, milestones, snippets and CI pipelines.

The development team has focused on keeping lab a simple and intuitive command line interface for commands provided in the GitLab API. lab's aim is to provide GitLab users an experience similar to the GitLab WebUI with respect to errors and messages.

Usage recommendation

One can use lab as a Git alias, integrating seamlessly to their Git workflow.

$ cat ~/.gitconfig
...
[alias]
    lab = "!lab"
    lab-i = "!lab issue"
    li = "!lab issue"

$ git lab mr list
$ git lab-i close
$ git li create

Also, lab can be set as shell aliases:

alias mrlist="lab mr list"

Installation

In compilation-time, lab depends only on other Go external modules, defined at go.mod. At runtime, git is required as many git commands are used by lab to retrieve local repository information.

Homebrew

brew install lab

NixOS

nix-env -f '<nixpkgs>' -iA gitAndTools.lab

Scoop

scoop install lab

Alpine

apk add lab

Bash

In case you don't want to install lab using any of the above package managers you can use the Bash script available:

:warning: The script will install lab into /usr/local/bin/.

curl -s https://raw.githubusercontent.com/zaquestion/lab/master/install.sh | sudo bash

:warning: Please take care when executing scripts in this fashion. Make sure you trust the developer providing the script and consider peeking at the install script itself (ours is pretty simple ;)

PreBuilt Binaries

Head to the releases page and download your preferred release.

Source

For building lab from source it's required Go 1.17+. Older versions (ie. 1.15) might still be able to build lab, but warnings related to unsupported go.mod format might be prompted.

git clone git@github.com:zaquestion/lab
cd lab
go install -ldflags "-X \"main.version=$(git rev-parse --short=10 HEAD)\"" .

or

make install

Configuration

lab needs your GitLab information in order to interact with to your GitLab instance. There are several ways to provide this information to lab:

Fresh start

When lab is executed for the first time, no suitable configuration found, it will prompt for your GitLab information. For example:

$ lab
Enter default GitLab host (default: https://gitlab.com):
Enter default GitLab token:

These informations are going to be save it into ~/.config/lab/lab.toml and won't be asked again. In case multiple projects require different information (ie. gitlab.com and a self-hosted GitLab service), using different configuration files as explained in the section below.

Configuration file

The most common option is to use lab configuration files, which can be placed in different places in an hierarchical style. The Tom's Obvious, Minimal Language (TOML) is used for the configuration file.

When a local configuration file is present (./lab.toml), no other configuration file will be checked, this will be the only one used for looking up required information.

However, other two options are possible:

1. User-specific: ~/.config/lab/lab.toml
2. Worktree-specific: .git/lab/lab.toml

These two files are merged before lab runs, meaning that they're complementary to each other. One thing is important to note though, options set in the worktree configuration file overrides (take precedence over) any value set in the user-specific file.

An example of user-specific configurations can be found below. As seen in the example file below, any command options specified by --help (for example lab mr show --help, or lab issue edit --help) can be set in the configuration file using TOML format.

[core]
  host = "https://gitlab.com"
  token = "1223334444555556789K"
  user = "yourusername"

[mr_checkout]
  force = true

[mr_create]
  force-linebreak = true
  draft = true

[mr_edit]
  force-linebreak = true

Local environment variables

If running lab locally, the variables LAB_CORE_HOST and LAB_CORE_TOKEN can be used, preventing configuration file creation/update. For example to use gitlab.com do:

export LAB_CORE_HOST="https://gitlab.com"

CI environment variables

The environment variables CI_PROJECT_URL, CI_JOB_TOKEN and GITLAB_USER_LOGIN, intended to be used in a CI environment, can be set to prevent any configuration file creation/update. Also, any of these take precedence over all other options.

Completions

lab provides completions for Bash, Elvish, Fish, Oil, Powershell, Xonsh and Zsh. Scripts can be directly sourced (though using pre-generated versions is recommended to avoid shell startup delay):

# bash (~/.bashrc)
source <(lab completion)

# elvish (~/.elvish/rc.elv)
eval (lab completion|slurp)

# fish (~/.config/fish/config.fish)
lab completion | source

# oil
source <(lab completion)

# powershell (~/.config/powershell/Microsoft.PowerShell_profile.ps1)
Set-PSReadlineKeyHandler -Key Tab -Function MenuComplete
lab completion | Out-String | Invoke-Expression

# xonsh (~/.config/xonsh/rc.xsh)
COMPLETIONS_CONFIRM=True
exec($(lab completion xonsh))

# zsh (~/.zshrc)
source <(lab completion zsh)

Contributing

We welcome all contributors and their contributions to lab! See the contribution guide.

What about GLab?

Both glab and lab are open-source tools with the same goal of bringing GitLab to your command line and simplifying the developer workflow. In many ways lab is to hub, what glab is to gh.

If you're looking for a tool like hub, less opinionated, that feels like using git and allows you to interact with GitLab then lab is for you. However, if you're looking for a more opinionated tool intended to simplify your GitLab workflows, you might consider using glab.