Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.aspect.build/llms.txt

Use this file to discover all available pages before exploring further.

The term “CD” is often ambiguous. Some engineers define it as Continuous Deployment—changes get released automatically, such as into a development environment. Aspect models Continuous Delivery differently: it’s the pipeline step where built artifacts upload to a well-known repository. This repository might be a container registry like Docker Hub, a blob store like AWS S3, or a database. This approach clearly separates CI/CD and Deployment responsibilities:
  • The CI/CD pipeline should upload only artifacts that are:
  • Configured with BUILD.bazel files.
  • Green (proving all relevant tests pass).
  • Changed from a previous build.
The deployment system then locates and promotes these artifacts to the next environment, such as dev, staging, or prod.

​
What’s “deliverable?”

A deliverable artifact contains the files to push and the pushing logic that performs the upload. It can also send a message to the deployment system to trigger an auto-deployment of the new artifact. In Bazel terms, a deliverable must be an executable program that you can Bazel run. Examples of deliverable targets include:
  • docker push: The oci_push or container_push rules run with bazel run to push a Docker image to a registry like Docker Hub.
  • git push: Use this when artifacts, such as an SDK, belong in a separate repository.
  • s3 sync: See the s3_sync example.

​
Which targets to deliver

Use a Bazel query expression to locate deliverable targets. You have two options to select targets:
  • Tagging scheme: Choose a scheme, like tags = ['artifact'].
  • Rule kinds: Deliver well-known rules, such as oci_push.
You can also use both options.

​
Which changes to deliver

To optimize time and money, deliver only changed targets. This avoids wasting time and resources uploading repeated artifacts. It also ensures release engineers don’t sort through duplicate lists. You can choose changed targets using two approaches:
  • Predict Changes: Use a git diff and tools like bazel-diff or target-determinator. These tools predict what’s affected by version control changes.
  • Determine Empirically: Find what’s actually different. This requires determinism, so use only unstamped build results (--nostamp).
Aspect recommends the second approach because the first has downsides:
  • bazel-diff is incorrect and may miss affected targets, preventing delivery.
  • target-determinator is slow. This hurts the service level indicator for releasing hot fixes.
  • It over-delivers, missing cases where source changes, for example a comment, don’t change the release binary.
The rest of this section details the empirical approach. Workflows first hashes the executable target to determine if you should deliver it on a commit. Use the Aspect outputs command with the special pseudo-mnemonic ExecutableHash, for example: 
$ aspect outputs 'attr("tags", "\bdeliverable\b", //...)' ExecutableHash
//cli:release h1:cj8OUC3l3fIr3Zxnffk6y7gukLOJmiWRCAQoqadg66Y=
//workflows/rosetta:release h1:kjHVajw+Nta2kh3Epcd32DkZxTE1NHA8b5N7hCNFNSM=
The output shows the target and its hash. The hash is a base64-encoded SHA256 of the executable file.

​
Debugging changes to delivered targets

Run the aspect outputs command locally to determine if a source file change creates a new executable. The results may differ from your expectations. For example:
  • Code comments: Changing a comment in a .go file doesn’t change the compiler’s output .a file. The executable hash remains unchanged.
  • External configuration: Changes to production configuration, like Helm charts for Kubernetes deployment, won’t cause a new delivery if they’re not inside the image.

​
Perform the delivery

Run each deliverable target with stamping enabled. You can do this using a script that reads targets from a manifest file, such as: cat $delivery_manifest | xargs -N1 bazel run --stamp. The Workflows configuration for Continuous Delivery follows the Aspect approach.

​
See also