Bazel Migration Survival Guide - Don't Let It Destroy Your Team

Before you start the Bazel migration that will consume the next 12-18 months of your life, let's do the math on whether you actually need this nightmare.

The Real Questions Your PM Won't Ask

Do you have 500+ developers? No? Don't migrate. Seriously. Bazel's benefits only kick in at Google scale. Your team of 30 engineers will spend more time fighting Bazel than benefiting from it.

Is your current build genuinely broken? "It takes 5 minutes" is not broken. "It randomly fails and we can't figure out why" might be. But if Gradle works fine and your biggest complaint is waiting for tests, you're solving the wrong problem.

Do you have a dedicated build engineer? Bazel isn't something you set up once and forget. You need someone who understands Starlark, can debug remote execution failures, and won't quit when builds break for the third time this month.

The Pinterest Timeline That Scared Everyone

Pinterest's migration took 18 months with a dedicated team and they're considered a success story. Here's what they didn't tell you in their blog post:

• First 3 months: Learning Starlark and figuring out why nothing compiles
• Month 4-6: Rewriting every BUILD file and discovering dependency hell
• Month 7-12: Fighting with remote execution and blaming AWS
• Month 13-15: Migrating from WORKSPACE to Bzlmod because Google deprecated WORKSPACE
• Month 16-18: Actually getting builds working consistently

Their senior engineer quit in month 10. The quote was "I'd rather debug Jenkins than deal with another Bazel error message."

What "Hermetic Builds" Actually Means

Bazel promises hermetic builds - your build only uses inputs you declare. Sounds great until you realize:

Your build depends on shit you didn't know about. That script that calls curl to download something? Dead. The test that reads /etc/hostname? Dead. The binary that expects to find java in PATH? Also dead.

System dependencies are everywhere. You'll spend weeks hunting down every place your code assumes GNU vs BSD tools, different Python versions, or that which gcc returns something useful.

The sandboxing breaks everything creative. Any clever build hack your team did - running Docker in Docker, calling out to external tools, generating code by shelling out - all broken.

I watched a team spend 2 weeks debugging the stupidest shit. Tests passed locally, failed in Bazel CI with:

FATAL ERROR in native method: No timezone info found for America/New_York

Turned out the tests were reading timezone data from /usr/share/zoneinfo and the sandbox doesn't include system directories. The "hermetic" fix? Vendor the entire fucking timezone database into their repo. 47MB of timezone data just to make tests pass.

This complexity is what makes Bazel migrations so painful - every hidden dependency becomes a sandbox violation you have to track down and fix.

The WORKSPACE → Bzlmod Migration Tax

Here's the fun part: WORKSPACE is dead. Bazel 9 removes it entirely. So if you migrate to Bazel now using WORKSPACE (because it's easier), you get to migrate again to Bzlmod within 2 years.

The Bzlmod migration breaks everything again:

• All your load() statements change
• Repository names change
• Module resolution conflicts with your carefully crafted dependency versions
• Every BUILD file needs updates

Teams are literally migrating twice. First WORKSPACE, then Bzlmod 18 months later when the first migration is barely stable.

The Infrastructure Bill Nobody Budgeted

Remote execution isn't optional at scale - it's the only way Bazel makes sense. But nobody tells you the real costs:

Compute costs explode. You're not just running builds on your laptop anymore. Every build hits a cluster of machines. I've seen AWS bills jump from $2k/month to $15k/month overnight.

Network bandwidth matters. Uploading build artifacts to remote cache for every commit adds up fast. One team I know hit their corporate 10Gbps limit after 3 weeks of Bazel remote execution. They had to explain to their IT director why the build system was consuming more bandwidth than their entire customer-facing website.

Cache storage costs. The remote cache that makes everything fast? It needs petabytes of storage. Budget $5k+/month for cache infrastructure that actually works.

Dedicated ops team. Remote execution clusters need babysitting. Machines crash, caches corrupt, network partitions happen. You need someone on call for your build system.

When Migration Actually Makes Sense

You should migrate to Bazel if you look like Google:

• 1000+ engineers touching the same codebase
• Multi-language monorepo (Go + Java + Python + JavaScript)
• Build times measured in hours, not minutes
• Cross-language dependencies everywhere
• Dedicated platform team with Bazel expertise

Everyone else should probably stick with language-native tools and save themselves 18 months of pain.

The question isn't "Should we use Bazel?" It's "Are we big enough that the 18-month migration cost is justified?"

For most teams, the answer is no.

Here's the shit sandwich: you migrate to Bazel using WORKSPACE, spend 12 months getting it stable, then Google says "WORKSPACE is deprecated, migrate to Bzlmod." So you get to migrate again.

Why WORKSPACE is Dead (And Why That Hurts)

WORKSPACE files are disabled in Bazel 8 and completely removed in Bazel 9. The writing's on the wall - if you use WORKSPACE, you're living on borrowed time.

But Bzlmod isn't just a simple find-and-replace. It's a completely different dependency resolution system that breaks assumptions your WORKSPACE build relied on.

The Real Bzlmod Migration Experience

I talked to the team at a mid-size startup who went through this twice. First WORKSPACE migration took 8 months. They thought they were done. Six months later, Bazel team announces WORKSPACE deprecation.

Month 1-2: Repository name chaos

Every external dependency changes names. @com_google_protobuf becomes @protobuf. @maven_//:guava becomes @maven.guava. Hundreds of BUILD files to update.

Month 3-4: Version conflicts everywhere

Minimal Version Selection picks different versions than your WORKSPACE did. Suddenly your carefully tested dependency matrix is fucked.

Their quote: "We spent 2 weeks debugging why protobuf generated different code. Turns out Bzlmod picked protobuf 3.21 while WORKSPACE used 3.19. Generated files were completely incompatible. Build passed, tests failed with:

java.lang.NoSuchMethodError: com.google.protobuf.GeneratedMessageV3$Builder.setUnknownFieldsProto3

Every protobuf class in the codebase needed regeneration."

Month 5-6: Module extension hell

Every macro you wrote for WORKSPACE needs conversion to module extensions. The concepts don't map cleanly.

WORKSPACE lets you call my_deps() anywhere. Bzlmod module extensions run once globally with specific tag syntax. You rewrite everything.

The Specific Breakages That Will Ruin Your Day

BUILD file repository references break:

## WORKSPACE style - dead
deps = ["@com_google_protobuf//java:protobuf"]

## Bzlmod equivalent - different name
deps = ["@protobuf//java:protobuf"]

Every BUILD file with external deps needs manual updates.

Macro loading paths change:

## WORKSPACE loads
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

## Bzlmod module extensions
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
## Different functions, different semantics

Version resolution conflicts:

Your WORKSPACE pinned guava to 28.0 because version 30 broke your code. Bzlmod's MVS picks 31.1 from a transitive dependency. Your builds break.

Override with single_version_override:

single_version_override(
    module_name = "rules_jvm_external",
    version = "4.3",
)

But now you're maintaining overrides for every dependency that has conflicts.

The Java Symbol Migration That Breaks Everything

Here's a specific clusterfuck: Java symbols (JavaInfo, java_common) moved from Bazel core to rules_java. Bazel 9 removes them entirely.

Your .bzl files that worked fine suddenly break with this cryptic bullshit:

ERROR: /Users/dev/project/BUILD:12:34: in java_binary rule //src/main:app:
Traceback (most recent call last):
  File "BUILD", line 12, column 34, in <toplevel>
  File "rules.bzl", line 45, column 12, in _java_binary_impl
Error: name 'JavaInfo' is not defined

No explanation of what JavaInfo is or where it went. Just "not defined" and good luck figuring it out.

The fix every Java rule needs:

load("@rules_java//java/common:java_info.bzl", "JavaInfo")
load("@rules_java//java/common:java_common.bzl", "java_common")

But this requires rules_java 7.5.0+. If your Bzlmod resolution picks an older version, you're fucked until you override it.

Local Repository Paths Break Everything

WORKSPACE local_repository used relative paths:

local_repository(
    name = "shared_lib",
    path = "../shared-library",
)

Bzlmod local_path_override needs absolute paths:

local_path_override(
    module_name = "shared_lib",
    path = "/absolute/path/to/shared-library",
)

Every developer needs different absolute paths. There's no clean solution - you end up with per-developer Bzlmod files or complex scripts to generate them.

The Testing Nightmare

Here's what nobody tells you: during WORKSPACE → Bzlmod migration, you need to test both systems in parallel. Your CI needs to:

1. Run WORKSPACE builds (existing system)
2. Run Bzlmod builds (new system)
3. Compare outputs and make sure they're identical
4. Debug every difference

We set up parallel CI pipelines. WORKSPACE passed, Bzlmod failed for 3 months straight. Every failure was a 4-hour debugging session to figure out why the two systems produced different outputs.

The Migration Strategy That Actually Works

Don't migrate everything at once. Create a MODULE.bazel file alongside your existing WORKSPACE. Use --enable_bzlmod flag to test Bzlmod builds while keeping WORKSPACE as fallback.

Start with minimal dependencies. Get basic builds working in Bzlmod before migrating complex dependency macros.

Expect repository name breakage. Budget 2-3 weeks just updating repository references in BUILD files.

Plan for version conflicts. Every dependency will need version investigation and potential single_version_override entries.

Keep WORKSPACE working during transition. You'll be switching back when Bzlmod builds break.

The timeline is 6+ months if you're methodical, 12+ months if you hit major version conflicts or complex macro conversions.

Why Teams Are Waiting

Smart teams are watching this shitshow and waiting. Why migrate to WORKSPACE when you know you'll migrate again to Bzlmod? Why migrate to Bzlmod when it's still breaking people?

The rational strategy: wait until Bzlmod is actually stable and WORKSPACE removal is imminent. Let other teams be the guinea pigs.

But Google's forcing the issue. WORKSPACE is gone in Bazel 9. If you want current Bazel versions, you migrate or you're stuck on Bazel 8 forever.