GitLab

Installs glab (the GitLab CLI) and configures shell aliases and per-shell account selection.

What it does

• Auto-installs and updates glab to the latest GitLab release (release tarball on Linux, Homebrew on macOS)
• Registers glab in ~/.versions.d/ so versions reports its version
• Bash tab completion for glab
• Keeps GitLab account selection per-shell (GLAB_CONFIG_DIR) so terminals never collide, see Per-shell isolation
• Stores each account's token in its own config file rather than the OS keyring, which is shared per host, see Credential storage
• Shell aliases and functions for merge-request, issue, and pipeline workflows

Variables

Variable	Default	Description
gitlab_glab_version	latest	Pin glab to an exact version, or track the newest release
gitlab_tmp_path	/tmp/glab/	Temporary directory for the glab download

Aliases

Alias	Command	Description
gitlab	glab-account	Show / switch the GitLab account
mrl	glab mr list	List merge requests
mrc	glab mr create	Create a merge request
mrv	glab mr view	View a merge request
gli	glab issue list	List issues
glci	glab ci status	Show the pipeline status

Functions

Function	Description
glab-authenticate	Select an account and run glab auth login in one step
glab-account	Show the current GitLab account, or switch to a named one: launches glab auth login if that account is signed out

Authentication

The role installs the binary but leaves you signed out, so nothing writes credentials during an apply. Sign in once per account with glab-authenticate, which selects the account's GLAB_CONFIG_DIR and then runs the interactive glab auth login:

glab-authenticate personal                            # gitlab.com (SaaS)
glab-authenticate client gitlab.client.example        # a self-hosted instance

glab-account on its own selects the shell's account, and launches the login for you when that account is signed out (glab-authenticate differs in that it always re-runs the login, even for an account already signed in):

glab-account personal        # select the account; if signed out, runs glab auth login

For non-interactive hosts (CI, headless), export a token instead and glab reads it without a login step:

export GITLAB_TOKEN=glpat-...

Credential storage

glab 1.111 made the operating system keyring the default store for new logins, so glab auth status nudges you whenever a token sits in the config file:

To store this token more securely, run glab auth login --hostname gitlab.example.com to move it into the operating system keyring.

The role declines that deliberately: glab-authenticate and glab-account both pass --insecure-storage, keeping the token in the account's own config.yml at mode 0600. glab keys keyring entries glab:<hostname>:<key> and never consults GLAB_CONFIG_DIR, so the keyring holds one credential per host for the whole OS user. Two accounts on the same host, the case per-account config dirs exist to solve, would overwrite each other's token there, and each shell would then silently act as the other identity. That failure is worse than a 0600 file, so file storage stays.

Two practical notes.

The nudge fires whenever the token came from the config file, whether or not a keyring backend exists. Headless Linux and WSL usually have no Secret Service on the session bus, so following it only prints The operating system keyring is unavailable and writes the same plaintext token back.

--insecure-storage needs glab 1.111 or newer. The default latest install has it; pinning gitlab_glab_version below that fails both functions with an unknown-flag error.

Git protocol

Both functions also pass --git-protocol ssh, which answers the Choose default Git protocol prompt before it appears. Left to itself the prompt preselects HTTPS, since glab only defaults to SSH when the login was given an --ssh-hostname that differs from the host:

gitProtocol := "https"
if opts.SSHHostname != "" && opts.SSHHostname != hostname {
    gitProtocol = "ssh"
}

The answer is then written per host, as hosts.<hostname>.git_protocol, and a per-host value outranks the top-level git_protocol that both glab and this role leave at ssh. So an enter keypress through the prompt is enough to move glab repo clone and the remotes glab creates for a new branch or merge request onto HTTPS against the stored token, while existing checkouts keep their git@ remotes and your key. Passing the flag keeps the two consistent.

Self-hosted instances

glab auth login offers two sign-in methods, Token and Web. Token works against any instance: generate a personal access token with the api and write_repository scopes and paste it at the prompt.

Web (OAuth) is gitlab.com-only out of the box, because glab ships a built-in client ID for the SaaS instance and has none for yours. Point it at a self-hosted host without one and the login stops at:

Set 'client_id' first with `glab config set client_id <client_id> -g --host <hostname>`.

To use Web against a self-hosted instance, register an OAuth application on it first (User settings → Applications, or at group or instance level):

Setting	Value
Redirect URI	http://localhost:7171/auth/redirect
Confidential	unchecked, since glab is a public client. Leaving it on fails the login with invalid_client.
Scopes	api, read_user, write_repository, openid, profile

Then store the application ID in the account's own config dir. glab config set honours GLAB_CONFIG_DIR, so select the account first:

glab-account client
glab config set client_id <APPLICATION_ID> --host gitlab.client.example
glab-authenticate client gitlab.client.example

Both functions prune credential-less hosts from the account's config once a login has run. glab seeds every new config dir with an empty gitlab.com entry, and glab auth status reports failure when any configured host holds no credential, so an account signed in only to a self-hosted instance would otherwise read as signed out and glab-account would relaunch the login on every call. Hosts holding a token, a keyring credential, or a client_id are left alone, so an account really does keep several instances at once. To clean up an account that predates this, run glab-authenticate <name> <hostname> again.

Multiple GitLab instances and accounts

glab stores credentials in a single config dir (~/.config/glab-cli), keyed per host under hosts:. That covers several different hosts at once out of the box: sign in to each and glab auto-selects the right one from the current repo's origin remote.

glab auth login                                  # gitlab.com (SaaS)
glab auth login --hostname gitlab.client.example # a self-hosted instance

What a single config dir cannot hold is two accounts on the same host (e.g. a personal and a work gitlab.com identity): one config keeps one token per host. glab-account solves that by giving each account its own config dir, scoped to the shell, and glab-authenticate selects one and logs in together:

glab-authenticate personal                     # ~/.config/glab/accounts/personal
glab-authenticate client gitlab.client.example # ~/.config/glab/accounts/client, self-hosted

glab-account <name> exports GLAB_CONFIG_DIR=~/.config/glab/accounts/<name>; run it with no argument to show the current account and list the ones you have. To override the host for a one-off command, glab still honours GITLAB_HOST:

GITLAB_HOST=gitlab.client.example glab issue list

Per-shell isolation

Account selection lives in the GLAB_CONFIG_DIR environment variable scoped to the current shell, never in a shared current account key. glab-account exports it rather than mutating one global config, so picking an account in one terminal cannot change which GitLab another terminal acts on.

Because selection is env-var driven, every terminal holds its own GitLab account. You can run several sessions at once, each signed in to a different account or instance, including a coding agent like Claude Code, with no shared glab state for them to fight over. The starship prompt reads the same GLAB_CONFIG_DIR/GITLAB_HOST and shows the account (🦊 <account>), so each shell visibly shows the GitLab it is on. This is the per-shell context isolation concept applied to GitLab.