All jobs

Migrate a Bazel WORKSPACE to Bzlmod

Yes. An agent replaces each WORKSPACE with a MODULE.bazel, maps http_archive rules to registry bazel_dep entries, builds every target with Bazel 9 and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent inventories every workspace root before it edits one, because a repository can hold several and they are rarely in the same state. In bazelbuild/examples, which is a collection of independent Bazel workspaces, most directories already have a MODULE.bazel and three still depend on a WORKSPACE alone: macros/, whose WORKSPACE is one comment line and whose .bazelversion says 8.0.0, with BUILD.bazel files that use genrule, exports_files and symbolic macros loaded from defs.bzl files in the same repository; make-variables/, whose WORKSPACE declares an http_archive for rules_cc 0.0.17 and whose testapp/BUILD loads @rules_cc//cc:cc_binary.bzl; and flags-parsing-tutorial/, whose WORKSPACE is workspace(name = "flags-parsing-examples") and whose BUILD defines four string_flag build settings from a local build_defs.bzl, exercised through a bazelrc file of --config groups. Other directories show the transition's middle states: java-maven/ keeps a marker WORKSPACE beside its MODULE.bazel and still sets common --enable_bzlmod in .bazelrc, and third-party-dependencies/ carries WORKSPACE, WORKSPACE.bzlmod and MODULE.bazel together. The rust-examples pin 9.* in .bazelversion, renovate.json enables the bazel, bazel-module and bazelisk managers, and no directory has a MODULE.bazel.lock except rust-examples/06-deps-direct.

Bazel's migration guide sets the deadline and the method: WORKSPACE is disabled by default in Bazel 8 and removed in Bazel 9, so the agent treats the three remaining files as the job. Each becomes a MODULE.bazel. macros/ gets a module(name = "macros_example") and nothing else, because it loads only files from its own tree; make-variables/ gets module(name = "make_variables_example") and bazel_dep(name = "rules_cc", version = "0.2.27"), the newest rules_cc in the Bazel Central Registry at the time of the run, with the http_archive and its SHA-256 gone, because the guide says a dependency that is in the registry is depended on with a bazel_dep directive; and flags-parsing-tutorial/ gets module(name = "flags-parsing-examples"), the same name its workspace() call used, so a label such as @flags-parsing-examples//:flag keeps resolving while the tutorial text moves to the //:flag form the guide recommends. The agent writes MODULE.bazel.lock wherever a build produces one and the directory's neighbours commit theirs, and deletes the three WORKSPACE files, which Bazel 9 no longer reads.

The middle states get tidied in the same pull request where it costs nothing: java-maven/.bazelrc loses common --enable_bzlmod, a flag that has been the default since Bazel 7, and third-party-dependencies/ loses WORKSPACE and WORKSPACE.bzlmod once its MODULE.bazel is confirmed to carry every dependency the two files did. Where a .bazelversion pins something older than 9, the agent leaves it alone and says so, because that pin is the example's own statement about what it supports; macros/ at 8.0.0 builds either way, since Bazel 8 already prefers MODULE.bazel. bazel mod tidy, which formats MODULE.bazel and updates use_repo calls for extensions, runs in each migrated directory, and bazel mod graph output goes into the pull request for make-variables/ so the reviewer sees rules_cc and its transitive platforms resolved from the registry.

Then it builds. The sandbox gets Bazelisk, which reads each directory's .bazelversion or takes the latest release, 9.3.1 at the time of the run, where there is none. In each migrated directory the agent runs bazel build //..., and where the README documents a command it runs that too: bazel build //testapp:show_predefined_variables followed by cat on the output file in make-variables/, bazel build //main:all in macros/, and bazel --bazelrc=./bazelrc build --config=foo :wibble in flags-parsing-tutorial/, the form its README uses, to confirm the string_flag values the README lists still print. For the directories that were already on Bzlmod it runs bazel build //... once to show the clean-up changed nothing. Because the repository has no CI workflow, the pull request includes the commands and their output as the record, and the agent proposes, without adding it, a workflow that runs them.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Migrate every Bazel workspace in this repository from WORKSPACE to Bzlmod. First list each directory that has a WORKSPACE, WORKSPACE.bzlmod, MODULE.bazel or .bazelversion and read the BUILD files, .bazelrc files and READMEs under it. For each directory without a MODULE.bazel, write one: a module() whose name matches any workspace(name) call, and a bazel_dep for every http_archive whose project is in the Bazel Central Registry, at the newest registry version; say so if any dependency is not in the registry and needs a module extension or use_repo_rule instead. Remove the WORKSPACE files and, where a MODULE.bazel already exists, the WORKSPACE, WORKSPACE.bzlmod and any --enable_bzlmod flag that is redundant. Leave each .bazelversion as it is. Run bazel mod tidy in each migrated directory, then bazel build //... and the commands each README documents, with Bazelisk choosing the Bazel version from .bazelversion or the latest release. Open a pull request that lists each directory, what replaced what, the bazel mod graph for directories with external dependencies, and the build output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

The pull request adds three MODULE.bazel files, removes the three WORKSPACE files, the WORKSPACE and WORKSPACE.bzlmod in third-party-dependencies/, and one line from java-maven/.bazelrc, and adds a MODULE.bazel.lock where a build produced one. Its description has a table with one row per directory: the Bazel version Bazelisk used, what the old file declared, what the new file declares, and the build command and its result. For make-variables/ it includes the bazel mod graph output showing rules_cc and the registry versions it pulled in.

A reviewer checks three things: that each bazel_dep version is the one they want rather than only the newest, since Renovate's bazel-module manager, already enabled in renovate.json, will keep it current from here; that the module names read well, because a module name becomes the repository name other modules see; and that the lock files match their policy, committed or ignored. Nothing about the BUILD files changed, so the examples still teach what they taught.

Run it on every repository still on WORKSPACE

A platform team with many Bazel repositories sends this body once per repository from its own server, each POST /o/{org}/sessions naming one repository in resources and carrying a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own WORKSPACE: a repository whose dependencies are all in the registry gets a complete MODULE.bazel, and one with a Go or Python toolchain registered through a repository rule gets the use_extension and use_repo calls for it, plus a note in the pull request for anything that still needs a WORKSPACE.bzlmod entry.

The key's webhook_url reports each run the key starts with the pull request URL in result, so a script that sent a dozen requests collects a dozen pull requests without polling.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

A Bzlmod migration is mechanical in outline and specific in every line: which registry version replaces which archive, which workspace() name to keep, which flag became the default two major versions ago, and which .bazelversion means the example should still build on Bazel 8. The agent reads those files, builds every target with the Bazel each directory asks for in its own sandbox, and keeps the build output and bazel mod graph in the run's record, so the pull request shows that each workspace still builds rather than asserting that it should.

A repository of many small workspaces, like this one, is exactly where a laptop migration drags: the same five steps in eleven directories, each with its own version pin and README commands. The agent does them all in one run and reports them in one table, and a fleet of repositories gets a pull request each, fitted to its own WORKSPACE.

Frequently asked questions

Why does this have to happen now?

Bazel's migration guide says WORKSPACE is disabled by default in Bazel 8 and removed in Bazel 9, which is the current major release. A directory that declared its dependencies only in WORKSPACE, as make-variables/ does with rules_cc, no longer finds them under the Bazel that Bazelisk downloads today, which is what the pull request's build table shows for each case.

What happens to an http_archive that is not in the registry?

The guide gives two paths: a use_repo_rule call in MODULE.bazel for a plain archive, or a module extension for anything with logic. The agent writes the use_repo_rule form when it can, and otherwise leaves the archive in a WORKSPACE.bzlmod file and says so in the pull request, because inventing a module extension is a design decision for the maintainer.

Will labels that used the old workspace name break?

Not if the module keeps it. The agent sets module(name = ...) to the old workspace(name = ...) value, and the guide notes that repo_name on module() can hold a different repository name where the two must differ. It also rewrites tutorial text to the //foo:bar form the guide recommends, where the name is not needed at all.

Should MODULE.bazel.lock be committed?

That is the repository's call. The agent follows what its neighbours do: in this repository one directory commits a lock file and the rest do not, so the pull request includes the new lock files and asks the reviewer to drop them if they prefer the other policy. bazel mod tidy refreshes a committed lock file whenever dependencies change.

Does it change the .bazelversion pins?

No. A pin is the example's statement about which Bazel it supports, and macros/ at 8.0.0 builds on Bzlmod already. The pull request lists each pin and notes which directories have none and so build with the latest release Bazelisk finds.

More Bazel jobs

More jobs like this: Hand off a long task

Keep reading