Skip to content

refactor(backend): deprecate ubi backend in favor of github #7374

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jdx merged 2 commits into from
Dec 18, 2025
Merged

refactor(backend): deprecate ubi backend in favor of github #7374

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
252b575
refactor(backend): deprecate ubi backend in favor of github
claude Dec 18, 2025
8cb84bf
[autofix.ci] apply automated fixes
autofix-ci[bot] Dec 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions docs/contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -644,7 +644,7 @@ of the full backend specification.

- **[aqua](dev-tools/backends/aqua.md)** - Preferred for GitHub releases with security
features
- **[ubi](dev-tools/backends/ubi.md)** - Simple GitHub/GitLab releases following
- **[github](dev-tools/backends/github.md)** - Simple GitHub releases following
standard conventions
- **Language package managers** - `npm`, `pipx`, `cargo`, `gem`, etc. for
ecosystem-specific tools
Expand All @@ -655,7 +655,7 @@ of the full backend specification.

```toml
your-tool.description = "Brief description of the tool"
your-tool.backends = ["aqua:owner/repo", "ubi:owner/repo"]
your-tool.backends = ["aqua:owner/repo", "github:owner/repo"]
your-tool.test = ["your-tool --version", "{{version}}"]
```

Expand All @@ -666,7 +666,7 @@ of the full backend specification.
When adding a new tool, the following requirements apply (automatically
enforced by [GitHub Actions workflow](https://github.com/jdx/mise/blob/main/.github/workflows/registry_comment.yml)):

- **New asdf plugins are not accepted** - Use aqua/ubi instead
- **New asdf plugins are not accepted** - Use aqua/github instead
- **A test is required in `registry.toml`** - Must include a `test` field to
verify installation
- **Tools may be rejected if they are not notable** - The tool should be
Expand All @@ -683,7 +683,7 @@ The `registry.toml` file uses this format:
your-tool.description = "Tool description"
your-tool.backends = [
"aqua:owner/repo", # Preferred backend first
"ubi:owner/repo", # Fallback backends
"github:owner/repo", # Fallback backends
"npm:package-name" # Multiple backends supported
]
your-tool.test = [
Expand Down Expand Up @@ -717,17 +717,17 @@ The test command should be reliable and the output pattern should use

Recent tool additions:

- **DuckDB**: Simple ubi backend ([#4248](https://github.com/jdx/mise/pull/4248))
- **DuckDB**: Simple github backend ([#4248](https://github.com/jdx/mise/pull/4248))

```toml
duckdb.backends = ["ubi:duckdb/duckdb"]
duckdb.backends = ["github:duckdb/duckdb"]
duckdb.test = ["duckdb --version", "{{version}}"]
```

- **Biome**: Multiple backends ([#4283](https://github.com/jdx/mise/pull/4283))

```toml
biome.backends = ["aqua:biomejs/biome", "ubi:biomejs/biome"]
biome.backends = ["aqua:biomejs/biome", "github:biomejs/biome"]
biome.test = ["biome --version", "Version: {{version}}"]
```

Expand All @@ -737,7 +737,7 @@ Recent tool additions:
**Most contributors want to add tools, not backends.** Before reading this
section, make sure you actually need a new backend. Tools are individual
software packages (like `node` or `ripgrep`), while backends are installation
mechanisms (like `aqua` or `ubi`). If you want to add a specific tool to mise,
mechanisms (like `aqua` or `github`). If you want to add a specific tool to mise,
see [Adding Tools](#adding-tools) instead.
:::

Expand All @@ -750,12 +750,12 @@ If you need a custom backend:

1. **Discuss with jdx first** in [Discord](https://discord.gg/UBa7pJUN7Z) or by
creating a [discussion](https://github.com/jdx/mise/discussions)
2. **Consider if existing backends** (ubi, aqua, npm, pipx, etc.) can meet your
2. **Consider if existing backends** (github, aqua, npm, pipx, etc.) can meet your
needs
3. **Create a plugin** - use the [plugin system](tool-plugin-development.md) to create plugins for private/custom tools without core changes. Start with the [mise-tool-plugin-template](https://github.com/jdx/mise-tool-plugin-template) for a quick setup

Most tool installation needs can be met by existing backends, especially
[ubi](dev-tools/backends/ubi.md) for GitHub releases and
[github](dev-tools/backends/github.md) for GitHub releases and
[aqua](dev-tools/backends/aqua.md) for comprehensive package management.
:::

Expand All @@ -769,7 +769,7 @@ across different installation systems.
Node.js, Python, Ruby
- **Package Manager Backends** (`src/backend/`) - npm, pipx, cargo, gem, go
modules
- **Universal Installers** (`src/backend/`) - ubi, aqua for GitHub releases and
- **Universal Installers** (`src/backend/`) - github, aqua for GitHub releases and
package management
- **Plugin Backends** (`src/backend/`) - plugins can provide custom backends or individual tools

Expand Down Expand Up @@ -835,7 +835,7 @@ across different installation systems.

Look at existing backends for patterns:

- `src/backend/ubi.rs` - Simple GitHub release installer
- `src/backend/github.rs` - Simple GitHub release installer

Copilot AI Dec 18, 2025

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The file reference src/backend/github.rs is incorrect. Based on the changes, the ubi backend file is being deprecated but still exists at src/backend/ubi.rs. If a github backend exists, it should be referenced correctly; if it doesn't exist yet, this documentation is misleading as it suggests viewing a file that may not exist.

Suggested change
- `src/backend/github.rs` - Simple GitHub release installer
- `src/backend/ubi.rs` - Simple GitHub release installer

Copilot uses AI. Check for mistakes.
- `src/backend/npm.rs` - Package manager integration
- `src/backend/core/node.rs` - Full language runtime implementation

Expand Down
8 changes: 6 additions & 2 deletions docs/dev-tools/backend_architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,11 +63,15 @@ Registry-based package manager with strong security features:
- **Sources**: Primarily GitHub but supports other sources through registry configuration
- **Security**: Comprehensive checksums, signatures, and verification

#### ubi - Universal Binary Installer
#### ubi - Universal Binary Installer (Deprecated)

::: warning
The ubi backend is deprecated. Use the [github backend](/dev-tools/backends/github) instead.
:::

Zero-configuration installer that works with any GitHub/GitLab repository following standard conventions:

- **Usage**: `ubi:BurntSushi/ripgrep`
- **Usage**: `ubi:BurntSushi/ripgrep` → migrate to `github:BurntSushi/ripgrep`
- **Requirements**: Repository must follow standard release tarball conventions
- **Sources**: Primarily GitHub releases, with GitLab support (rarely used in mise)
- **Configuration**: None required - automatically detects and downloads appropriate binaries
Expand Down
9 changes: 7 additions & 2 deletions docs/dev-tools/backends/ubi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,13 @@
# Ubi Backend

::: warning
The ubi backend is **deprecated**. Please use the [github backend](/dev-tools/backends/github) instead.

To migrate, replace `ubi:owner/repo` with `github:owner/repo` in your configuration files.
:::

You may install GitHub Releases and URL packages directly using [ubi](https://github.com/houseabsolute/ubi) backend. ubi is directly compiled into
the mise codebase so it does not need to be installed separately to be used. ubi is preferred over
plugins for new tools since it doesn't require a plugin, supports Windows, and is really easy to use.
the mise codebase so it does not need to be installed separately to be used.

ubi doesn't require plugins or even any configuration for each tool. What it does is try to deduce what
the proper binary/tarball is from GitHub releases and downloads the right one. As long as the vendor
Expand Down
2 changes: 1 addition & 1 deletion docs/walkthrough.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -231,5 +231,5 @@ For further reading:
- [Configuration](/configuration) – More information on `mise.toml` files
- [Settings](/configuration/settings) – All the configuration settings available in mise
- [Backends](/dev-tools/backends/) – An index of all the backends available in mise
- [Registry](/registry) – Every "shorthand" available for tools in mise like `node`, `terraform`, or `watchexec` which point to `core:node`, `asdf:asdf-community/asdf-hashicorp`, and `ubi:watchexec/watchexec` respectively
- [Registry](/registry) – Every "shorthand" available for tools in mise like `node`, `terraform`, or `watchexec` which point to `core:node`, `asdf:asdf-community/asdf-hashicorp`, and `aqua:watchexec/watchexec` respectively
- [CLI](/cli/) – The full list of commands available in mise
4 changes: 2 additions & 2 deletions e2e/cli/test_registry
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
#!/usr/bin/env bash

assert "mise registry gh" "aqua:cli/cli ubi:cli/cli[exe=gh] asdf:bartlomiejdanek/asdf-github-cli"
assert_contains "mise registry" "gh aqua:cli/cli ubi:cli/cli[exe=gh] asdf:bartlomiejdanek/asdf-github-cli"
assert "mise registry gh" "aqua:cli/cli asdf:bartlomiejdanek/asdf-github-cli"
assert_contains "mise registry" "gh aqua:cli/cli asdf:bartlomiejdanek/asdf-github-cli"

# --json flag tests
assert "mise registry gh --json | jq -r '.short'" "gh"
Expand Down
Loading
Loading