# 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 Rush](https://cloud.getrush.ai/run/migrate-to-bzlmod/bazel/). Opens 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`

```json
{
  "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.

## 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

- [Write Unit Tests for a C++ Project Built with Bazel](https://getrush.ai/run/write-unit-tests/bazel/)
- [Add a Buildifier Check to CI for a Bazel Repository](https://getrush.ai/run/add-buildifier-to-ci/bazel/)
- [Generate compile_commands.json for a Bazel C++ Project](https://getrush.ai/run/add-compile-commands/bazel/)

## More jobs like this: Hand off a long task

- [Replace setTimeout Polling With chrome.alarms in a Chrome Extension](https://getrush.ai/run/migrate-to-chrome-alarms/chrome-extension/)
- [Migrate an Expo App from React Navigation to Expo Router](https://getrush.ai/run/migrate-to-expo-router/expo/)
- [Migrate an Ansible Role to Fully Qualified Collection Names](https://getrush.ai/run/migrate-to-fqcn/ansible/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
