GitLab Backend

You may install GitLab release assets directly using the gitlab backend. This backend downloads release assets from GitLab repositories and is ideal for tools that distribute pre-built binaries through GitLab releases.

The code for this is inside of the mise repository at ./src/backend/github.rs.

Usage

The following installs the latest version of gitlab-runner from GitLab releases and sets it as the active version on PATH:

$ mise use -g gitlab:gitlab-org/gitlab-runner
$ gitlab-runner --version
gitlab-runner 16.8.0

The version will be set in ~/.config/mise/config.toml with the following format:

[tools]
"gitlab:gitlab-org/gitlab-runner" = { version = "latest", asset_pattern = "gitlab-runner-linux-x64" }

Authentication

For private repositories or higher API limits, mise supports several GitLab token sources.

Token priority

mise checks these sources in order and uses the first token found:

1. MISE_GITLAB_ENTERPRISE_TOKEN (for non-gitlab.com hosts)
2. MISE_GITLAB_TOKEN
3. GITLAB_TOKEN
4. credential_command (if set)
5. gitlab_tokens.toml (per host)
6. glab CLI config (config.yml, if enabled)
7. git credential fill (if gitlab.use_git_credentials=true)

Environment variables

export MISE_GITLAB_TOKEN="glpat-xxxxxxxx"

For self-hosted GitLab instances:

export MISE_GITLAB_ENTERPRISE_TOKEN="glpat-yyyyyyyy"

Token file (gitlab_tokens.toml)

# ~/.config/mise/gitlab_tokens.toml
[tokens."gitlab.com"]
token = "glpat-xxxxxxxx"

[tokens."gitlab.mycompany.com"]
token = "glpat-yyyyyyyy"

credential_command

You can provide a shell command that prints a token to stdout:

[settings.gitlab]
credential_command = "op read 'op://Private/GitLab Token/credential'"

The target hostname is passed as $1 to the command.

glab CLI integration

mise can read tokens from glab config as a fallback. It checks:

1. $GLAB_CONFIG_DIR/config.yml
2. $XDG_CONFIG_HOME/glab-cli/config.yml (defaults to ~/.config/glab-cli/config.yml)
3. ~/Library/Application Support/glab-cli/config.yml (macOS)

Disable this fallback with:

[settings.gitlab]
glab_cli_tokens = false

git credential fill fallback

As a last resort, mise can query git credential helpers:

[settings.gitlab]
use_git_credentials = true

This uses git credential fill and supports credentials stored by helpers such as macOS Keychain.

Debugging token resolution

Use mise token gitlab to see which token mise would use for a given host:

mise token gitlab
mise token gitlab --unmask
mise token gitlab gitlab.mycompany.com

Tool Options

The following tool-options are available for the gitlab backend—these go in [tools] in mise.toml.

Asset Autodetection

When no asset_pattern is specified, mise automatically selects the best asset for your platform. The system scores assets based on:

• OS compatibility (linux, macos, windows)
• Architecture compatibility (x64, arm64, x86, arm)
• Libc variant (gnu or musl for Linux, msvc for Windows)
• Archive format preference (tar.gz, zip, etc.)
• Build type (avoids debug/test builds)

For most tools, you can simply install without specifying patterns:

mise install gitlab:user/repo

::: tip The autodetection logic is implemented in src/backend/asset_matcher.rs, which is shared by both the GitHub and GitLab backends. :::

asset_pattern

Specifies the pattern to match against release asset names. This is useful when there are multiple assets for your OS/arch combination or when you need to override autodetection.

[tools."gitlab:gitlab-org/gitlab-runner"]
version = "latest"
asset_pattern = "gitlab-runner-linux-x64"

version_prefix

Specifies a custom version prefix for release tags. By default, mise handles the common v prefix (e.g., v1.0.0), but some repositories use different prefixes like release-, version-, or no prefix at all.

When version_prefix is configured, mise will:

• Filter available versions with the prefix and strip it
• Add the prefix when searching for releases
• Try both prefixed and non-prefixed versions during installation

[tools]
"gitlab:user/repo" = { version = "latest", version_prefix = "release-" }

Examples:

• With version_prefix = "release-":
  • User specifies 1.0.0 → mise searches for release-1.0.0 tag
  • Available versions show as 1.0.0 (prefix stripped)
• With version_prefix = "" (empty string):
  • User specifies 1.0.0 → mise searches for 1.0.0 tag (no prefix)
  • Useful for repositories that don't use any prefix

Platform-specific Asset Patterns

For different asset patterns per platform:

[tools."gitlab:gitlab-org/gitlab-runner"]
version = "latest"

[tools."gitlab:gitlab-org/gitlab-runner".platforms]
linux-x64 = { asset_pattern = "gitlab-runner-linux-x64" }
macos-arm64 = { asset_pattern = "gitlab-runner-macos-arm64" }

checksum

Verify the downloaded file with a checksum:

[tools."gitlab:owner/repo"]
version = "1.0.0"
asset_pattern = "tool-1.0.0-x64.tar.gz"
checksum = "sha256:a1b2c3d4e5f6789..."

Instead of specifying the checksum here, you can use mise.lock to manage checksums.

Platform-specific Checksums

[tools."gitlab:gitlab-org/gitlab-runner"]
version = "latest"

[tools."gitlab:gitlab-org/gitlab-runner".platforms]
linux-x64 = {
  asset_pattern = "gitlab-runner-linux-x64",
  checksum = "sha256:a1b2c3d4e5f6789...",
}
macos-arm64 = {
  asset_pattern = "gitlab-runner-macos-arm64",
  checksum = "sha256:b2c3d4e5f6789...",
}

size

Verify the downloaded asset size:

[tools]
"gitlab:gitlab-org/gitlab-runner" = { version = "latest", size = "12345678" }

Platform-specific Size

You can specify different sizes for different platforms:

[tools."gitlab:gitlab-org/gitlab-runner"]
version = "latest"

[tools."gitlab:gitlab-org/gitlab-runner".platforms]
linux-x64 = { size = "12345678" }
macos-arm64 = { size = "9876543" }

strip_components

Number of directory components to strip when extracting archives:

[tools]
"gitlab:gitlab-org/gitlab-runner" = { version = "latest", strip_components = 1 }

::: info If strip_components is not explicitly set, mise will automatically detect when to apply strip_components = 1. This happens when the extracted archive contains exactly one directory at the root level and no files. This is common with tools like ripgrep that package their binaries in a versioned directory (e.g., ripgrep-14.1.0-x86_64-unknown-linux-musl/rg). The auto-detection ensures the binary is placed directly in the install path where mise expects it. :::

bin

Rename the downloaded binary to a specific name. This is useful when downloading single binaries that have platform-specific names:

[tools."gitlab:myorg/mytool"]
version = "1.0.0"
asset_pattern = "mytool-linux-x86_64"
bin = "mytool"  # Rename from mytool-linux-x86_64 to mytool

::: info When downloading single binaries (not archives), mise automatically removes OS/arch suffixes from the filename. For example, mytool-linux-x86_64 becomes mytool automatically. Use the bin option only when you need a specific custom name. :::

rename_exe

Rename the executable after extraction from an archive. This is useful when the archive contains a binary with a platform-specific name that you want to rename:

[tools."gitlab:myorg/mytool"]
version = "latest"
asset_pattern = "mytool_linux.zip"
rename_exe = "mytool"  # Rename the extracted binary to mytool

::: tip Use rename_exe for archives where the binary inside has a different name than desired. Use bin for single binary downloads (non-archives). :::

bin_path

::: v-pre Specify the directory containing binaries within the extracted archive, or where to place the downloaded file. This supports Tera templating with variables like {{ version }}, {{ os }}, {{ arch }}, and arch aliases ({{ darwin_os }}, {{ amd64_arch }}, {{ x86_64_arch }}, {{ gnu_arch }}): :::

[tools."gitlab:gitlab-org/gitlab-runner"]
version = "latest"
bin_path = "gitlab-runner-{{ version }}/bin" # expands to gitlab-runner-1.0.0/bin

Binary path lookup order:

1. If bin_path is specified, use that directory
2. If bin_path is not set, look for a bin/ directory in the install path
3. If the install path root contains an executable file, use the install path root
4. If no bin/ directory exists, search subdirectories for bin/ directories
5. If no bin/ directories are found, searches immediate subdirectories for any executable files. If an executable is found directly within a subdirectory, that entire subdirectory is considered a binary path.
6. If no executables are found, use the root of the extracted directory

filter_bins

Comma-separated list of binaries to symlink into a filtered .mise-bins directory. This is useful when the tool comes with extra binaries that you do not want to expose on PATH.

[tools]
"gitlab:myorg/mytool" = { version = "1.0.0", filter_bins = "mybin" }

When enabled:

• A .mise-bins subdirectory is created with symlinks only to the specified binaries
• Other binaries are not exposed on PATH

api_url

For self-hosted GitLab instances, specify the API URL:

[tools]
"gitlab:myorg/mytool" = { version = "latest", api_url = "https://gitlab.mycompany.com/api/v4" }

Private GitLab repositories

If you want to install a tool from a private repository on gitlab.com, set the MISE_GITLAB_TOKEN environment variable for authentication:

export MISE_GITLAB_TOKEN="your-token"

Self-hosted GitLab

If you are using a self-hosted GitLab instance, set the api_url tool option and optionally the MISE_GITLAB_ENTERPRISE_TOKEN environment variable for authentication:

export MISE_GITLAB_ENTERPRISE_TOKEN="your-token"

Supported GitLab Syntax

• GitLab shorthand for latest release version: gitlab:gitlab-org/gitlab-runner
• GitLab shorthand for specific release version: gitlab:gitlab-org/[email protected]

Settings