description: "Versioning is a critical part of delivering software to users. With bazel, you can derive per-build values and inject them anywhere in your build process."
In my [last post](/2024/09/the-joy-of-versioning/) I spent some time talking about how more rigorous versioning helped reduce wasted time debugging and upgrading code as it started getting broken into lots of little pieces.
That post was pretty light on direct `bazel` usage but I promise, it'll pay off. Here, we're going to cover how to use these tags *in* your builds to tag docker images or inject build information into compiled binaries.
I'm assuming that you've read the [first bazel post](/2023/08/beautiful-builds-with-bazel/) in this series, or that you've already got your bazel + bzlmod setup going.
## Stamping and you
Bazel includes functionality that it calls "stamping". Bazel has to separate this into its own conceptual space because one of the core design principles is build reproducibility: for bazel's caching to work, inputs have to be deterministic and ideally change infrequently between runs.
Bazel's [documentation](https://bazel.build/docs/user-manual#workspace-status) covers the bare essentials, with a small caveat. Stamping requires a script , the "workplace status" script, that emits space-separated key-value pairs, e.g. `STABLE_KEY_NAME VALUE`. An example script is included below.
One important detail that the documentation doesn't cover is that your workspace status script **cannot** live in the root of your bazel project. You have two options:
- Place the status script somewhere in your `$PATH`
- Place the status script in a subdirectory
Still not sure why, but if you simply do `bazel --workplace_status_command=status.sh`, `bazel` will *only* look for it in your `$PATH`.
## Build Injection
Using the variables created by your workspace status script ends up being incredibly simple, if you're using `rules_go`. the `x_defs` parameter lets you override values at compile-time, exactly for cases like this.
```
x_defs = {
"Version": "{STABLE_STAMP_VERSION}",
"Build": "{STABLE_STAMP_COMMIT}",
},
```
This is equivalent to the Go build flag `-ldflags "-X PACKAGENAME.Version=whatever -X PACKAGENAME.BUILD=whatever"`. It's important to note that the raw Go flags require a fully qualified package name be specified. Bazel is smart enough to derive the necessary package name on its own, all you have to do is tell it which variable needs to be overriden with what value.
## Putting it all together
The final, full invocation for stamping your builds should look something like this.
```
wikilink-obsidian-resolver on main [⇡] via 🐹 v1.22.2
❯ bazel run --stamp --workspace_status_command=tools/workspace_status.sh //cmd/version
INFO: Build completed successfully, 1 total action
wikilink-obsidian-resolver on main [⇡] via 🐹 v1.22.2
❯ ./dist/bin/cmd/version/version_/version
Version: v0.1.4-1-g5792d62
Build: 5792d623fc9fc1852aeb09dd008eabb640cb6711
```
## What next?
Stamping is not going to accomplish any of my goals on its own, but it was an important part of preparing my toolkit. If I'm going to release software for other people to consume, I need versioning. Injecting a git tag into a Go binary is a trivial proof of concept; I'll be using this to automatically tag and push OCI images and probably other stuff I haven't come up with yet.
## Notes, Warnings, Caveats
- Important: the `workspace-status-script`*cannot* live in the root of the bazel project. It has to be in a subdirectory for some reason.
- If you're defining `x_defs` on a `rules_go``go_library`, you cannot fully qualify the variable names.
- To find where bazel places artifacts, use `bazel cquery --output=files`
