repository_rules.md

June 3, 2026 · View on GitHub

Public API for repository rules

rb_bundle

load("@rules_ruby//ruby:deps.bzl", "rb_bundle")

rb_bundle(toolchain, **kwargs)

Wraps rb_bundle_rule() providing default toolchain name.

PARAMETERS

Name	Description	Default Value
toolchain	default Ruby toolchain BUILD	`"@ruby//:BUILD"`
kwargs	underlying attrs passed to rb_bundle_rule()	none

rb_register_toolchains

load("@rules_ruby//ruby:deps.bzl", "rb_register_toolchains")

rb_register_toolchains(name, version, version_file, msys2_packages, portable_ruby,
                       portable_ruby_release_suffix, portable_ruby_checksums, resolved_version,
                       register, **kwargs)

(For MRI on Linux and macOS) Installed using ruby-build.
(For MRI on Windows) Installed using RubyInstaller.
(For JRuby on any OS) Downloaded and installed directly from official website.
(For TruffleRuby on Linux and macOS) Installed using ruby-build.
(With portable_ruby) Portable Ruby downloaded from bazel-contrib/portable-ruby.
(For "system") Ruby found on the PATH is used. Please note that builds are not hermetic in this case.

When portable_ruby = True, this function registers a Bazel toolchain per supported execution platform so that builds resolve to the right interpreter on remote execution and cross-platform setups. Per-platform repositories @<name>_<platform> are created lazily — Bazel only fetches the one matching the resolved exec platform. A hub repository @<name> aliases the canonical targets (:bundle, :gem, :ruby, :headers, :jars, etc.) via select(), preserving direct references like @ruby//:bundle.

JRuby's archive is platform-independent (JVM-based), so it is registered as a single unconstrained toolchain — no per-platform repos needed.

Other modes (ruby-build for MRI source compile, TruffleRuby, RubyInstaller, system) remain single-platform host-only.

WORKSPACE:

load("@rules_ruby//ruby:deps.bzl", "rb_register_toolchains")

rb_register_toolchains(
    version = "3.0.6"
)

Once registered, you can use the toolchain directly as it provides all the binaries:

$ bazel run @ruby -- -e "puts RUBY_VERSION"
$ bazel run @ruby//:bundle -- update
$ bazel run @ruby//:gem -- install rails

You can also use Ruby engine targets to select() depending on installed Ruby interpreter:

BUILD:

rb_library(
    name = "my_lib",
    srcs = ["my_lib.rb"],
    deps = select({
        "@ruby//engine:jruby": [":my_jruby_lib"],
        "@ruby//engine:truffleruby": ["//:my_truffleruby_lib"],
        "@ruby//engine:ruby": ["//:my__lib"],
        "//conditions:default": [],
    }),
)

PARAMETERS

Name	Description	Default Value
name	base name of resulting repositories, by default "ruby"	`"ruby"`
version	a semver version of MRI, or a string like [interpreter type]-[version], or "system"	`None`
version_file	.ruby-version or .tool-versions file to read version from	`None`
msys2_packages	extra MSYS2 packages to install	`["libyaml"]`
portable_ruby	when True, downloads portable Ruby from bazel-contrib/portable-ruby instead of compiling via ruby-build. Has no effect on JRuby, TruffleRuby, or Windows.	`False`
portable_ruby_release_suffix	release suffix for portable Ruby (default "1", e.g. "2" downloads X.Y.Z-2).	`""`
portable_ruby_checksums	platform checksums for portable Ruby downloads, overriding built-in checksums.	`{}`
resolved_version	the version string resolved from `version_file` by the module extension. Used to detect JRuby (which skips the multi-platform `portable_ruby` path since its archive is platform-independent).	`None`
register	whether to register the resulting toolchains, should be False under bzlmod	`True`
kwargs	additional parameters to the downloader for this interpreter type	none

rb_bundle_fetch

load("@rules_ruby//ruby:deps.bzl", "rb_bundle_fetch")

rb_bundle_fetch(name, srcs, auth_patterns, bundler_checksums, bundler_remote, env, gem_checksums,
                gemfile, gemfile_lock, jar_checksums, netrc, repo_mapping, ruby)

Fetches Bundler dependencies to be automatically installed by other targets.

Currently doesn't support installing gems from Git repositories, see https://github.com/bazel-contrib/rules_ruby/issues/62.

WORKSPACE:

load("@rules_ruby//ruby:deps.bzl", "rb_bundle_fetch")

rb_bundle_fetch(
    name = "bundle",
    gemfile = "//:Gemfile",
    gemfile_lock = "//:Gemfile.lock",
    srcs = [
        "//:gem.gemspec",
        "//:lib/gem/version.rb",
    ]
)

Checksums for gems in Gemfile.lock are printed by the ruleset during the build. It's recommended to add them to gem_checksums attribute.

WORKSPACE:

rb_bundle_fetch(
    name = "bundle",
    gemfile = "//:Gemfile",
    gemfile_lock = "//:Gemfile.lock",
    gem_checksums = {
        "ast-2.4.2": "1e280232e6a33754cde542bc5ef85520b74db2aac73ec14acef453784447cc12",
        "concurrent-ruby-1.2.2": "3879119b8b75e3b62616acc256c64a134d0b0a7a9a3fcba5a233025bcde22c4f",
    },
)

All the installed gems can be accessed using @bundle target and additionally gems binary files can also be used via BUILD rules or directly with bazel run:

BUILD:

load("@rules_ruby//ruby:defs.bzl", "rb_test")

package(default_visibility = ["//:__subpackages__"])

rb_test(
    name = "rubocop",
    main = "@bundle//bin:rubocop",
    deps = ["@bundle"],
)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this repository.	Name	required
srcs	List of Ruby source files necessary during installation.	List of labels	optional	`[]`
auth_patterns	A list of patterns to match against urls for which the auth object should be used.	Dictionary: String -> String	optional	`{}`
bundler_checksums	Custom map from Bundler version to its SHA-256 checksum.	Dictionary: String -> String	optional	`{}`
bundler_remote	Remote to fetch the bundler gem from.	String	optional	`"https://rubygems.org/"`
env	Environment variables to use during installation.	Dictionary: String -> String	optional	`{}`
gem_checksums	SHA-256 checksums for remote gems. Keys are gem names (e.g. foobar-1.2.3), values are SHA-256 checksums.	Dictionary: String -> String	optional	`{}`
gemfile	Gemfile to install dependencies from.	Label	required
gemfile_lock	Gemfile.lock to install dependencies from.	Label	required
jar_checksums	SHA-256 checksums for JAR dependencies. Keys are Maven coordinates (e.g. org.yaml:snakeyaml:1.33), values are SHA-256 checksums.	Dictionary: String -> String	optional	`{}`
netrc	Path to .netrc file to read credentials from	String	optional	`""`
repo_mapping	In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository. For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`). This attribute is not supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function).	Dictionary: String -> String	optional
ruby	Override Ruby toolchain to use for installation.	Label	optional	`None`

rb_bundle_rule

load("@rules_ruby//ruby:deps.bzl", "rb_bundle_rule")

rb_bundle_rule(name, srcs, env, gemfile, repo_mapping, toolchain)

(Deprecated) Use rb_bundle_fetch() instead.

Installs Bundler dependencies and registers an external repository that can be used by other targets.

WORKSPACE:

load("@rules_ruby//ruby:deps.bzl", "rb_bundle")

rb_bundle(
    name = "bundle",
    gemfile = "//:Gemfile",
    srcs = [
        "//:gem.gemspec",
        "//:lib/gem/version.rb",
    ]
)

All the installed gems can be accessed using @bundle target and additionally gems binary files can also be used:

BUILD:

load("@rules_ruby//ruby:defs.bzl", "rb_binary")

package(default_visibility = ["//:__subpackages__"])

rb_binary(
    name = "rubocop",
    main = "@bundle//:bin/rubocop",
    deps = ["@bundle"],
)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this repository.	Name	required
srcs	List of Ruby source files used to build the library.	List of labels	optional	`[]`
env	Environment variables to use during installation.	Dictionary: String -> String	optional	`{}`
gemfile	Gemfile to install dependencies from.	Label	optional	`None`
repo_mapping	In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository. For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`). This attribute is not supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function).	Dictionary: String -> String	optional
toolchain	-	Label	required