Generate it, then ship it

git checkout step-6
git diff step-5 step-6

The three binaries in this repository have had a service.yaml beside them since the last step, inert, waiting for something to read them:

cmd/server/service.yaml (abridged)

name: server
port: 8080
replicas: 3
healthcheck: /healthz

That is a convention — “a package with a service.yaml is a service” — and conventions are what nobody wants to hand-write BUILD files for. Only name and port are read by anything; the rest of the file, including a resources: block this snippet leaves out, is there to look like a real deployment descriptor. Gazelle already generates go_library and go_binary by reading Go sources. This step teaches it one more rule.

Run it

The generated targets are already committed at this step, so throw them away first and ask for them back:

git restore --source=step-5 -- cmd/*/BUILD.bazel
aspect gazelle

→ ✅ Passed gazelle task · Updated 3 BUILD files

Look at what came back in cmd/server/BUILD.bazel:

go_cross_binary(
    name = "server_linux",
    platform = "@rules_go//go/toolchain:linux_amd64",
    target = ":server",
)

tar(
    name = "server_layer",
    srcs = [":server_linux"],
    include_runfiles = False,
)

oci_image(
    name = "image",
    architecture = "amd64",
    entrypoint = ["/cmd/server/server_linux"],
    exposed_ports = ["8080/tcp"],
    labels = {
        "org.opencontainers.image.title": "server",
    },
    os = "linux",
    tars = [":server_layer"],
)

oci_push(
    name = "push",
    image = ":image",
    remote_tags = ["1h"],
    repository = "ttl.sh/server",
)

Four targets, from two keys. port: 8080 became exposed_ports; name: server became the image label and the push repository.

How it works

Open tools/gazelle/service_image.axl. An extension has two halves. prepare says what to read.

sources = [aspect.SourceFiles("service.yaml"), aspect.SourceExtensions(".go")],
queries = {
    "name": aspect.YamlQuery(filter = "service.yaml", query = ".name"),
    "port": aspect.YamlQuery(filter = "service.yaml", query = ".port"),
},

Matchers and yq expressions. Packages without a service.yaml cost nothing. The engine running this is called Orion — that is the name in the last line of the file, and it is why the repository can use a prebuilt Gazelle with no Go toolchain. declare says what targets belong in one package. Two of the four it adds are plumbing — go_cross_binary and tar exist to get a Linux binary into a layer, and neither comes from the YAML. The two your service.yaml actually shapes are image and push.

ctx.targets.add(name = "image", kind = "oci_image", attrs = {...})

It is handed the answers for a package and adds targets. If there is no service.yaml, it calls ctx.targets.remove(...) instead — which is how a generated target disappears when its YAML does. After declare there is one gazelle_rule_kind registration per rule this extension writes. Each names three things:

From — where the rule comes from, a .bzl label or a bare module name like @tar.bzl. This is what writes the load statements you saw at the top of the generated BUILD file.
MergeableAttrs — attributes the generator owns, re-asserted on every run.
NonEmptyAttrs — the attribute whose absence means the rule is dead. It is what lets ctx.targets.remove(...) actually delete a target rather than leave an empty one behind.

How Gazelle finds it

A task under .aspect/ needs no registration. A Gazelle extension does — it is named by the Gazelle binary that hosts it, which step-6 also added:

tools/gazelle/BUILD.bazel

aspect_gazelle(
    name = "gazelle",
    extensions = ["service_image.axl"],
    languages = ["go"],
    repo_config = None,
)

That is the binary aspect gazelle drives, and it is the prebuilt one because only that binary hosts Orion. The comments in the file cover repo_config, which is required whenever go is in languages.

It is idempotent

aspect gazelle

✅ All BUILD files are up to date.

Nothing to do, because the generated targets already match what the YAML says. Now change the YAML and run it again:

sed -i '' 's/port: 8080/port: 9090/' cmd/server/service.yaml
aspect gazelle
git diff -- cmd/server/BUILD.bazel

exposed_ports follows. That is MergeableAttrs doing its job: the generator owns that attribute, so a re-run re-asserts it.

git checkout -- .

Then ship it

The generated oci_push targets are real. aspect delivery runs them:

aspect delivery --mode=always --track-state=false

TARGET             STATUS       DURATION  KEY  BUILD URL
//cmd/cron:push    OK (FORCED)  7.8s      -    -
//cmd/server:push  OK (FORCED)  10.3s     -    -
//cmd/worker:push  OK (FORCED)  3.0s      -    -

Summary: 3 delivered, 0 skipped, 0 pending, 0 failed  (22.5s total)

Crane logs every layer as it uploads, so expect a wall of pushed blob: lines before the table. Three images, live on ttl.sh — an anonymous registry that needs no account and expires an image an hour after it is pushed.

ttl.sh has one global namespace, so everyone in a workshop pushes to the same three repositories. The builds are reproducible, so everyone pushes identical bytes and the tag expires within the hour — but if you would rather have your own, change _REGISTRY in the extension to ttl.sh/<something-unique> and re-run aspect gazelle.

Nothing here was hand-written: a service.yaml became BUILD targets, and the BUILD targets became images. config.axl is what told delivery where to look:

ctx.tasks["delivery"].args.query = 'kind("oci_push rule", //...)'

Every oci_push in this repository was generated from a service.yaml, so that query means “all of them”. Next: hand all of this to an agent.

Get started

Platform

Aspect Cloud

Aspect Enterprise

Aspect CLI

Bazel

Learning

Generate it, then ship it

Run it

How it works

How Gazelle finds it

It is idempotent

Then ship it

​Run it

​How it works

​How Gazelle finds it

​It is idempotent

​Then ship it

Run it

How it works

How Gazelle finds it

It is idempotent

Then ship it