Skip to main content
Every aspect delivery invocation produces a delivery manifest: a structured record of every target’s outcome (ok / skip / warn / fail / pending), the resolved CI metadata (host, build URL, commit), and each target’s delivery metadata: structured data your target and hooks attached, stored with the delivery and returned whenever a later run reuses it. By default the manifest uploads as one JSON CI artifact (delivery-manifest.json) and surfaces as a labeled download link on the GitHub Status Check / Buildkite annotation. Pass --manifest-file=<path> to also write the manifest to disk. DeliveryTrait hooks are set in .aspect/config.axl, which loads it with load("@aspect//traits.axl", "DeliveryTrait"). These customize what the manifest carries and what happens with it:
  • skip_policy(target): picks each target’s skip policy before the skip decision.
  • delivery_target(entry): fires once per delivery target with its terminal outcome plus on-disk paths. Return a dict to add to that target’s metadata (e.g. attach an OCI image digest); when the target is delivered, the metadata is stored with the delivery.
  • render_manifest_file(manifest): return the string written to --manifest-file. Default is pretty-printed JSON. Only fires when --manifest-file is set.
  • upload_manifest(manifest): return the list of CI artifacts to upload. Default is one JSON artifact (delivery-manifest.json). Return [] to disable uploads; return multiple entries to split the manifest across files / formats.
  • delivery_manifest(manifest): fires once at end-of-task with the full structured manifest. Use for in-process actions like assembling an OCI layer, posting to an escrow registry, or writing an audit log.
These take no arguments and bracket the run:
  • delivery_start(): fires once at the start of the run, before any target is resolved or delivered.
  • delivery_end(): fires once after every target has been dispatched and the summary printed. Unlike delivery_manifest, it doesn’t fire when the task exits early.
Each hook receives only the entry or manifest dict, no context. When a hook needs ctx.std or ctx.template, define it inside config(ctx) so it closes over the ConfigContext, the same pattern task hooks use for shared state.

Manifest shape

The manifest is a stable, documented dict, safe to serialize to JSON and to consume from any downstream tooling:
counts has a key only for outcomes that occurred, so read it with .get(outcome, 0). dry_run_build is how the document expresses --dry-run=build: with both it and dry_run true, the preview ran the build, so the per-target on-disk paths are populated. message is display text whose meaning depends on the outcome (a URL on ok / skip, an error on fail); read delivered.build_url for the URL of the build that delivered a target. metadata and delivered are described under Delivery metadata. Treat unknown fields as additive: Aspect may add new top-level or per-entry fields in future releases without bumping schema_version, as long as the additions are non-breaking.

Delivery metadata

Delivery metadata, skip policies and the delivery API require Aspect CLI v2026.45.15 or later. Every entry carries metadata: data your target or hooks attach, such as a run URL or an image digest. Aspect never writes inside it. When the target is delivered, the metadata is stored with the delivery, and when a later run skips the target it comes back with the entry, so a reused delivery looks the same to your hooks, manifest, and templates as a fresh one. An entry for a target that was delivered, in this run or an earlier one, also carries delivered:
Each delivered field is null when unknown. A fail, warn or pending entry has no delivered.

Write metadata from the delivery target

Each delivery target runs with ASPECT_DELIVERY_METADATA_JSON_FILE set to a path. Write a JSON object there and it becomes the entry’s metadata:
deliver.sh
The file is optional. A file over 64 KiB, or one that isn’t a JSON object, is ignored with a warning.

Where the data goes

A failed attempt clears the stored delivery of the digest it tried, so the next run delivers it again. Nothing is stored under --track-state=false. When the file and the hook set the same key, the hook’s value wins. If the hook’s additions push the metadata over 64 KiB, only the metadata file’s contents are stored. A top-level __proto__ key is reserved and dropped with a warning. Store facts about the delivery, such as a run URL or an image digest, never paths on the runner: a later run reads the metadata back on a different machine.

Show metadata in the status check

A delivery details template sees each outcome group’s entries (up to 50 per group), metadata and delivered included, under groups[].entries. Set it for the delivery task in task_templates on each surface that should show it, GithubStatusChecks and BuildkiteAnnotations; it replaces the default details. This one renders what the deliver.sh above writes:
.aspect/config.axl
A missing key renders as empty, but reading a field of a missing value (such as e.delivered.build_url on an entry with no delivered) is an error, so guard optional fields with is defined.

Where deliveries are stored

Where aspect delivery keeps its state depends on where it runs:
  • On an Aspect Workflows runner, in the runner’s deliveryd, the daemon at ASPECT_WORKFLOWS_DELIVERY_API_ENDPOINT. A deliveryd that serves API v2 behaves like the delivery API: it stores metadata, tracks each target’s latest delivery and keeps every attempt. API v2 needs Aspect Workflows 6.1.12 or later and Aspect CLI v2026.46.10 or later; an older Aspect CLI keeps speaking API v1 to it. The run’s State: line names the API it uses.
  • Everywhere else, in Aspect’s delivery API, metadata included.
Neither falls back to the other: a backend that can’t be used fails the job at startup. So does a deliveryd that lists no API version this Aspect CLI speaks; upgrade the Aspect CLI. The delivery API authenticates with your Aspect credential: aspect auth login locally, ASPECT_API_TOKEN in CI. The token’s role needs the Delivery: write permission (aspect.delivery.write), which every role with remote cache write access includes. A token with only Delivery: read (aspect.delivery.read) can run --dry-run. The API keeps each target’s latest delivery and each digest’s for at least 365 days after it was recorded. A delivery run that checks a delivery extends that, best effort and at most once a day, so a target that keeps being checked stays delivered. Every delivery attempt, failures included, stays in the target’s history for at least 3 years. To use the delivery API on Workflows runners too, for example while a runner’s deliveryd serves only API v1 (before Aspect Workflows 6.1.12), or to share delivery state with jobs that run off runners, set it in config:
.aspect/config.axl
The job needs ASPECT_API_TOKEN from your CI’s secret store: on GitHub Actions, pass it to setup-aspect’s aspect-api-token input; on Buildkite, add secrets: [ASPECT_API_TOKEN] to the delivery step, and the setup-aspect plugin logs in with it. The API starts empty, so the first run after the switch delivers every target once. The runner’s deliveryd keeps its state in your deployment’s Redis, and API v2 expires it with the delivery API’s retention periods. When Redis is full, it evicts the least recently used state rather than failing, and a target whose state was evicted is delivered again. A deliveryd that serves v2 also expires API v1 state. A commit’s recorded digests expire 90 days after the build, so an API v1 delivery of an older commit finds nothing to deliver. A delivery expires 365 days after it was recorded, extended like a v2 delivery when a run checks it. State written before the upgrade, which has no expiry, gets one in the background: 90 days for digests and 365 for deliveries, counted from when deliveryd reaches it, and 90 days for leftovers of older Workflows delivery tasks.
API v1 and v2 keep separate state, so the first run in which both the Aspect CLI and the runner’s deliveryd speak v2 delivers every target once. While your runners or CLIs are a mix of both, as during a rolling upgrade, a digest new to both can be delivered once by each, so twice in all. Eviction from a full Redis also delivers a target again. Before upgrading, check that delivering a once_per_digest target again is safe, for example a push of a fixed version to a package registry.

Deprecated backends

Both of these will be removed from the Aspect CLI in an upcoming release, and the delivery task warns when it uses either:
  • deliveryd API v1, which the CLI speaks to a deliveryd that doesn’t serve v2. It stores the delivering build URL only and doesn’t track a target’s latest delivery. On it, metadata works for the run that writes it (the task warns once that it isn’t stored), a later skip has empty metadata and only delivered.build_url, and every target behaves as once_per_digest. Upgrade Aspect Workflows so the runner’s deliveryd serves API v2.
  • redis_state.connect, which reads and writes the Redis that backs deliveryd directly, at ASPECT_WORKFLOWS_DELIVERY_REDIS_ENDPOINT. It stores metadata and the rest of delivered, but doesn’t track a target’s latest delivery, so every target behaves as once_per_digest. Remove it from DeliveryState.connect to use the runner’s deliveryd. Its state is API v1’s, so the switch to v2 delivers every target once (see the warning above).

Skip policy

Each target is skipped by one of two policies: when_changed needs a backend that tracks each target’s latest delivery: the delivery API, or a deliveryd that serves API v2. On the deprecated backends, every target behaves as once_per_digest. Under once_per_digest, a digest delivered by one target counts for every target with that digest: a skip then carries that delivery’s metadata and delivered, with delivered.label naming the target that delivered it. A target opts into once_per_digest with a tag:
BUILD.bazel
To choose in code, set DeliveryTrait.skip_policy. It receives {label, tags, policy}, where policy is what the tags resolved to, and returns "when_changed", "once_per_digest", or None to keep policy:
.aspect/config.axl
tags come from the change-detection build, so they’re empty under --mode=always --track-state=false without --dry-run, which skips it. --force-target and --mode=always deliver regardless of the skip policy. Each entry carries its skip_policy.

Per-target enrichment

DeliveryTrait.delivery_target(entry) fires once per delivery target after its outcome is decided. For a target delivered in this run (ok), it fires before the delivery is recorded, so whatever it returns is stored with it. The hook receives the entry: its manifest fields, including the on-disk paths (on this runner) for reading sibling outputs the rule produced. The paths are in the manifest too: Return value:
  • None: metadata stays as it is.
  • A dict: keys merge into entry["metadata"], overriding any the metadata file set.
  • Anything else: the task fails with an error, so typos surface.
The metadata is stored and written to the manifest, so it must encode as JSON. If the hook raises, or leaves metadata that JSON can’t encode, no further deliveries start and the delivery build is cancelled:
  • The target whose hook failed is still recorded, with only its metadata file’s contents.
  • Targets already running finish and are recorded as usual.
  • Targets that never started fail with hook_error.
The task writes the manifest, then exits non-zero (the build’s exit code when the build itself failed), naming each target whose hook failed. Materialization guarantee: for a target the delivery build built, its runfiles tree is on disk when the hook fires: the build downloads top-level outputs (raising --remote_download_outputs to toplevel when it’s minimal) and builds each target’s runfiles tree from its manifest, as bazel run does. Files declared via data = [...] are readable at runfiles_workspace_dir/<package>/<filename>. Files in default_outputs but not in runfiles reach disk as top-level outputs; reach them by path from the default_outputs list.

Example: attach an OCI image digest

A common case: your push rule (e.g. rules_oci’s oci_push) writes a sibling .digest file alongside the binary. Read it from inside the runfiles tree and attach it to the metadata:
.aspect/config.axl
The resulting manifest entry now carries:
The hook returns None for anything but ok, because a skip entry already carries the digest stored when the image was pushed (on a backend that stores metadata; a skip on deliveryd API v1 has empty metadata).

Example: read a sibling default output not in runfiles

Some rules (rules_oci push, among others) write outputs that are in the target’s default output group but not reachable via runfiles. Scan default_outputs by suffix instead:
.aspect/config.axl
default_outputs is the full list of files BES reported in the target’s default output group, with absolute filesystem paths. Files in runfiles are also here; the value is in scanning for ruleset-specific outputs that only live in default_outputs. The hook records the file name, not the path: its return value is stored with the delivery, and a path names a file on this runner only. To act on the file in this run, read it inside the hook.

Combining patterns

The two patterns compose: read the digest from runfiles (with _runfiles_path from the first example), then scan default outputs for any sibling layer:
.aspect/config.axl

Custom rendering

The on-disk file (--manifest-file) and the CI artifact have separate renderers, render_manifest_file and upload_manifest, so you can ship JSON for tooling and YAML for humans (or any other split) from the same run.

render_manifest_file: content of --manifest-file

DeliveryTrait.render_manifest_file(manifest) returns the string written to --manifest-file. Default (hook unset, or hook returns None) is pretty-printed JSON via json.encode(manifest, indent = 2). Aspect ships with Jinja2 (ctx.template.jinja2); pair it with an inline template stored next to the hook so the template + interpretation live together:
.aspect/config.axl
The data kwarg’s keys become top-level template variables. That’s why the template references deliveries, not data.deliveries. The is defined guard skips the line on entries whose metadata doesn’t carry image_digest. Set --manifest-file=delivery-manifest.yml so the on-disk file carries the right extension. The default upload takes its name from --manifest-file but is always JSON, so also set upload_manifest when the file is YAML. Contract:
  • Must return a string or None. Anything else fails the task with a clear error.
  • Returning None falls back to the default JSON rendering, for hooks that want to render conditionally (e.g. YAML on CI, JSON locally).
  • Only fires when --manifest-file is set. With no --manifest-file, this hook is never called.
  • Receives the same structured dict documented under Manifest shape.

upload_manifest: what gets uploaded as CI artifacts

DeliveryTrait.upload_manifest(manifest) returns the list of CI artifacts to upload. Each entry is a dict {"name": str, "content": str}: name is the artifact basename (controls extension), content is the rendered bytes. Default (hook unset, or hook returns None) uploads one JSON artifact (delivery-manifest.json, or the basename of --manifest-file when set). Return [] to disable uploads entirely. The structured manifest dict is still passed to delivery_manifest regardless.
.aspect/config.axl
Return one entry to swap format / name. The status surfaces show a single link labeled by name:
.aspect/config.axl
Return multiple entries to split the manifest across files / formats. For example, ship the full JSON for downstream tooling alongside a focused YAML side-artifact listing only the OCI images and their digests:
.aspect/config.axl
The Jinja2 template filters to delivered entries, whether delivered in this run (ok) or reused (skip), that have an image_digest (set by the delivery_target hook from the earlier example). So the YAML side-artifact lists every image the commit ships, and stays focused on the OCI subset even when the manifest also covers non-OCI deliverables (a sh_binary ops script, etc.). layer_file renders only when the hook also captured one; is defined is the guard for any optional field. A more elaborate split, with separate files per consumer:
.aspect/config.axl
Each uploaded file gets its own labeled link on the status surface (GitHub Status Check / Buildkite annotation), labeled by name and in the order the hook returned. The same files are also reachable via the Artifacts browse link. Contract:
  • Must return a list or None. Anything else fails the task with a clear error.
  • Each entry must be a dict with non-empty name (string) and content (string).
  • Returning None falls back to the single-JSON default; returning [] disables uploads.
  • Receives the same structured dict documented under Manifest shape.

End-of-task actions

DeliveryTrait.delivery_manifest(manifest) fires once at end-of-task with the full structured manifest, after every target’s delivery_target hook has merged into its metadata, and after the on-disk file is written and the CI artifact uploaded. Use for in-process actions that need the complete picture:
.aspect/config.axl
The hook receives the structured dict (not any of the rendered strings render_manifest_file / upload_manifest produced) so you don’t have to re-parse anything. Early exits fire too. The hook runs on every exit the task handles (validation failures, build failures, failed targets), not only successful runs. An empty deliveries list means no target was resolved; a build failure gives every target a warn entry. An error raised by a delivery_target hook stops further deliveries, and the task exits non-zero after writing the manifest; so does one raised by delivery_start or delivery_end, or a state backend that fails before delivery starts. A state write that fails is warned about, the run continues, and the task exits 1.

CLI flags

Order of operations

  1. delivery_start() fires.
  2. Under --mode=selective, the state backend is asked about every target’s digest. skip_policy(target) then picks each target’s policy, in every mode.
  3. Each target’s outcome is decided. A target that runs has the file at $ASPECT_DELIVERY_METADATA_JSON_FILE read into metadata; a skipped target gets the metadata and delivered stored when it was delivered.
  4. delivery_target(entry) fires for that target; the returned dict merges into entry["metadata"].
  5. For a delivered target, the delivery is recorded in the state backend with its metadata. A failed one has the stored delivery of its digest cleared so the next run retries it; the delivery API also records the failed attempt in the target’s history.
  6. After every target has been dispatched, the summary prints and delivery_end() fires.
  7. The manifest is built from the recorded outcomes.
  8. When --manifest-file is set: render_manifest_file(manifest) is called (default JSON when unset or it returns None); the result is written to disk.
  9. upload_manifest(manifest) is called (default: one JSON artifact when unset or it returns None); each entry uploads as a CI artifact.
  10. The final status update posts; the GitHub status check and Buildkite annotation show one labeled link per uploaded artifact.
  11. delivery_manifest(manifest) fires with the structured dict (not the rendered strings).
delivery_manifest runs last, so a hook that raises there doesn’t block the on-disk file, the artifact upload, or the final status update.

See also