- docs
- Publish and integrate
- Publish and integrate
- Integrations
- Use OCX with Bazel
Use OCX with Bazel
This page shows how to provision a Bazel workspace’s tools through OCX with the rules_ocx module, and which OCX settings apply while Bazel fetches them. It covers the OCX side only. The Bazel side lives in the rules_ocx documentation.
rules_ocx never re-implements OCX in Starlark. It downloads a pinned ocx binary inside a repository rule and drives that binary. The contracts it relies on are your ocx.lock and the OCI manifests.
Provision the workspace toolchain
Start from a Bazel workspace with bzlmod enabled and an ocx.lock that ocx lock wrote next to your ocx.toml. Add the module, point it at both files, and list the repository it creates:
bazel_dep(name = "rules_ocx", version = "0.5.0")
ocx = use_extension("@rules_ocx//ocx:extensions.bzl", "ocx")
ocx.project( name = "tools", ocx_toml = "//:ocx.toml", ocx_lock = "//:ocx.lock",)
use_repo(ocx, "tools")Every executable that the toolchain’s packages declare as their public surface becomes a runnable target named @tools//:<name>. Use it in tools =, in $(location ...) and in bazel run.
A test target consumes one through data and finds its path with $(location ...):
load("@rules_shell//shell:sh_test.bzl", "sh_test")
sh_test( name = "lint", srcs = ["lint_test.sh"], data = ["@tools//:shellcheck"], env = {"SHELLCHECK_BIN": "$(location @tools//:shellcheck)"},)Run bazel run to start a tool directly, and bazel query to list the targets the rule created:
bazel run @tools//:shellcheck -- --versionbazel query @tools//...ShellCheck - shell script analysis toolversion: <version>...@tools//:shellcheck@tools//:shfmtEach tool in your ocx.toml appears in the query output, one label per executable. A declared tool that is missing raises no error, so check the list when a target you expect is absent.
The same toolchain then serves your shell, your CI and Bazel. A fetch uses the shared OCX_HOME store, so a package that a developer pulled is not downloaded again for Bazel on that machine. The project toolchain page explains how ocx.toml and ocx.lock relate.
A single package that is not in your project takes ocx.package(name = "jq", package = "ocx.sh/jqlang/jq:latest"). Pin it by digest when the build must not move.
What the rules ask of OCX
A repository rule calls three OCX commands, so those are the ones to test when a fetch fails:
| Step | Command |
|---|---|
| Staleness gate | ocx lock --check |
| Download | ocx pull for a project, ocx package install for a single package |
| Environment | ocx --format json env --pinned |
A failed step reports an exit code and error document. A stale lock fails the fetch with exit 65, the same as in any pipeline. Run ocx lock and commit the result.
Settings that reach a fetch
Bazel runs a repository rule from its own working directory, with its own environment. rules_ocx therefore forwards a fixed set of variables and sets a few others itself. The list that matters to an operator:
- Registry traffic:
OCX_MIRRORS,OCX_INSECURE_REGISTRIESand theOCX_AUTH_<REGISTRY>_*variables from Authenticate to GHCR and ECR. Bazel cannot enumerate the auth variables, so runbazel fetch --forceafter you change one. - Resolution:
OCX_INDEX,OCX_OFFLINE,OCX_FROZEN,OCX_REMOTE,OCX_JOBSandOCX_DEFAULT_REGISTRY. - Configuration:
OCX_CONFIG,OCX_NO_CONFIG,OCX_MANAGED_CONFIGandOCX_PATCHES. - Trust:
OCX_SIGSTORE_TRUSTED_ROOTandOCX_EXTRA_CA_CERTS. The second one is how a corporate proxy CA reaches Bazel.
rules_ocx does not forward OCX_NO_VERIFY or OCX_ALLOW_YANKED to a fetch. A build that must skip verification or accept a yanked package says so in MODULE.bazel with ocx.policy(...), so an exported variable cannot weaken a fetch silently.
The rules_ocx guides cover the Bazel half of this: the offline mirror guide and the trust and config concepts.
Choose a different surface
- Without Bazel, use GitHub Actions, GitLab CI or the Docker image.
- To run Bazel itself from OCX, list
bazelin yourocx.tomland callocx exec -- bazel ....