Skip to main content
The legacy Rosetta delivery system used two YAML-configured tasks:
  • delivery_manifest — queried Bazel for deliverable targets, hashed their outputs, and recorded a manifest in Redis.
  • delivery — read the manifest from Redis and ran bazel run on each new target, signing completed deliveries to prevent repeats.
aspect delivery collapses both into a single command, shaped by three orthogonal flags:
  • --mode={selective,always} (default selective) — the delivery model. selective uses change detection: only runs candidates that haven’t already been delivered for the --task:name[:--salt] prefix. always skips change detection and treats every resolved target as a delivery candidate (closest analogue to the legacy “always deliver” model — --force-target is redundant).
  • --dry-run (default off) — print what would be delivered, don’t actually run anything.
  • --track-state={true,false} (default true) — whether to track delivery state across runs (record what’s been delivered, query before re-delivering). Required (true) when --mode=selective — selective delivery has no meaning without persisted state. Set to false outside Aspect Workflows CI runners (where the state backend isn’t yet available).
This migration only affects how delivery is triggered and tracked. The delivery targets themselves (bazel run-able rules tagged deliverable) do not need to change.
The flags compose:
CombinationBehaviorPrerequisites
--mode=selective (default)selective; runs candidates; records statestate backend, remote cache
--mode=selective --dry-runselective preview; records digests for future runs; no runstate backend, remote cache
--mode=alwaysruns every target; records digests + deliveriesstate backend, remote cache
--mode=always --dry-runalways preview; records digests; no runstate backend, remote cache
--mode=always --track-state=falseruns every target; nothing recorded; no digests computednone
--mode=always --dry-run --track-state=falsebest-effort preview without state tracking; nothing recorded; no runremote cache (optional — degrades to a digest-less list if missing)
--mode=selective --track-state=false (any --dry-run)invalid — selective delivery requires state—
--mode=selective --track-state=false is rejected — selective delivery has no meaning without persisted state. For previews outside Aspect Workflows CI runners use --mode=always --dry-run --track-state=false; to actually run targets without state tracking use --mode=always --track-state=false. See Requirements below for the constraints on each prerequisite.

​
What determines “needs delivery”

Legacy YAML-configured tasks: a target was new if its Bazel output hash had never been recorded in Redis (SETNX). The salt could be customized via salt_envs. Aspect CLI: change detection considers a target new if the combination of its action digest (a stable hash of the target’s action graph) and the change-detection prefix has not been recorded by the state backend. The prefix is --task:name alone, or --task:name:--salt when both are provided.
Because the action digest is computed by the remote cache protocol — not by hashing local output files — it is stable across machines and rebuild attempts. Two runners producing bit-identical outputs derive the same digest, so change detection correctly skips the second delivery.
Always set --task:name explicitly. If you omit it, the CLI generates a random one per invocation, which shifts the change-detection scope every run and every target will be re-delivered every time. Pick a stable identifier for your pipeline (e.g. delivery, production-deploy) and reuse it across runs.

​
Requirements

The combination matrix above shows which prerequisites apply per invocation. Two notes worth highlighting:
  • The remote cache derives action digests via Bazel’s gRPC log. It’s required whenever digests are recorded or surfaced in --dry-run output — i.e. everywhere except --mode=always --track-state=false (which builds and runs targets directly without computing digests). For --mode=always --dry-run --track-state=false the cache is optional: if configured, digests appear in the preview; if not, the preview prints a NOTE and lists candidates without digests.
  • The state backend records what’s been delivered. It’s started automatically on Aspect Workflows CI runners. Pass --track-state=false outside Aspect Workflows CI runners.
The state backend is currently available only on Aspect Workflows CI runners. Leaving --track-state=true (the default) on other CI hosts or local machines fails at startup with ASPECT_WORKFLOWS_DELIVERY_API_ENDPOINT is not set. The delivery state backend must be running. Outside Aspect Workflows CI runners, switch to --mode=always: pair with --dry-run --track-state=false for a digest preview, or with --track-state=false alone to actually deliver every target. State-tracking support outside Aspect Workflows CI runners is planned for a future release.

​
What changed

AreaYAML-configured tasksAspect CLI tasks
Invocationrosetta run delivery_manifest then rosetta run delivery (two-step pipeline reading/writing a manifest in Redis)aspect delivery (single command)
Targets (query)deliverable: '<query>' (query expression)--query '<query>' — e.g. aspect delivery --query 'attr("tags", "deliverable", //...)'
Targets (label list)deliverable: [//foo, //bar]pass labels positionally — e.g. aspect delivery //foo //bar
Stamp flags (--stamp, --workspace_status_command)stamp_flags: [<flags>]Use --release-bazel-flag=<flag> — not --bazel-flag. Release flags apply only to the final delivery build, so they don’t shift the change-detection digest. --release-bazel-flag defaults to --stamp, so stamping is already on; add --release-bazel-flag=--workspace_status_command=<path> for a custom status script. See Stamp and release-only flags.
Other Bazel flags—Repeat --bazel-flag=<flag> for each entry — e.g. --bazel-flag=--jobs=100. These apply to every build phase, including change detection, so use them only for flags that don’t change outputs. A release --config that enables stamping is non-deterministic — pass it as --release-bazel-flag=--config=release instead.
Saltsalt_envs: [A, B] (list of env var names; values concatenated automatically)--salt "$A:$B" — compose the string yourself and pass a single value. Appended to --task:name to scope change detection.
Dry-run / manifest-onlymanifest_only: true--dry-run
Forced re-delivery (per-rule)only_on_change: false on a rule (disable change detection for every target the rule produces)--force-target=//foo:bar per target (granularity shifts from rule → specific label), or --mode=always to disable change detection for every target in the invocation
Forced re-delivery (env var)ASPECT_WORKFLOWS_DELIVERY_TARGETS=//foo,//bar (comma-separated)ASPECT_WORKFLOWS_DELIVERY_FORCE_TARGETS="//foo //bar" (whitespace-separated) — merged with any --force-target=... flags. Repeating --force-target=//foo --force-target=//bar works too. Each label must already be in the resolved delivery set (from --query / positional args): force-target only flips the change-detection skip; unmatched labels hard-fail at startup.
Branch filtercondition: { branches: [...] }run aspect delivery only from the relevant CI branch step
Tag filtercondition: { tags: [...] }run aspect delivery only from the relevant CI tag step
Limit querylimit_querynot needed — scope the --query expression directly
State storeredis_url / redis_use_tlsnot applicable (the state backend replaces Redis)
Triggerauto_deliver: truenot applicable — calling aspect delivery is itself the trigger
Workspacesworkspaces: top-level listnot applicable — cd <dir> in your CI config and run aspect delivery from there

​
Examples

The CI examples below omit --commit-sha and --build-url: both are auto-detected from CI environment variables (GITHUB_SHA / BUILDKITE_COMMIT / CIRCLE_SHA1 / CI_COMMIT_SHA for the SHA; the corresponding run/build URL for the build URL). Pass them explicitly only when you need to override the detected values — for instance, if your CI host isn’t recognized or you want to attribute the delivery to a different commit. On GitHub Actions pull_request events, detection picks the PR-head SHA rather than the synthetic merge SHA in GITHUB_SHA. On GitHub Actions, the build URL is upgraded from the run page (/actions/runs/<id>) to the specific job page (/actions/runs/<id>/job/<job_id>) when the Aspect Workflows GitHub App is installed and the ASPECT_API_TOKEN in use has a role granting actions: read (e.g. GitHub CI or GitHub Token: actions — see GitHub token roles and scopes). If not, the run URL is used.

​
Query-based delivery on main

Before — .aspect/workflows/config.yaml: 
tasks:
  - delivery:
      auto_deliver: true
      rules:
        - deliverable: 'attr("tags", "\\bdeliverable\\b", //...)'
          condition:
            branches: [main]
After — CI configuration: 
on:
  push:
    branches: [main]

jobs:
  deliver:
    runs-on: aspect-workflows
    permissions:
      id-token: write   # ArtifactUpload uses the runner's OIDC token to call the GitHub Actions artifact API
    steps:
      - uses: actions/checkout@v4
      - uses: aspect-build/setup-aspect@2306377a61c45954ab2df7c7311698b109364352 # v2026.26.9
        with:
          aspect-api-token: ${{ secrets.ASPECT_API_TOKEN }}
      - name: Deliver
        run: |
          aspect delivery \
            --query 'attr("tags", "deliverable", //...)' \
            --task:name delivery

​
Multi-condition rules (branches and tags)

Before — .aspect/workflows/config.yaml: 
tasks:
  - delivery:
      auto_deliver: true
      rules:
        - deliverable: 'set(//services/...)'
          condition:
            branches: [main, 'hotfix/.*']
        - deliverable: [//tools:release]
          condition:
            tags: ['v[0-9]+\.[0-9]+\.[0-9]+']
After — CI configuration: 
on:
  push:
    branches: [main, 'hotfix/**']
    tags: ['v[0-9]+.[0-9]+.[0-9]+']

jobs:
  deliver:
    runs-on: aspect-workflows
    permissions:
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - uses: aspect-build/setup-aspect@2306377a61c45954ab2df7c7311698b109364352 # v2026.26.9
        with:
          aspect-api-token: ${{ secrets.ASPECT_API_TOKEN }}

      - name: Deliver services
        if: github.ref_type == 'branch'
        run: |
          aspect delivery \
            --query 'set(//services/...)' \
            --task:name delivery

      - name: Deliver release
        if: github.ref_type == 'tag'
        run: |
          aspect delivery \
            //tools:release \
            --task:name delivery

​
Dry-run / manifest-only mode

Use --dry-run to preview what would be delivered without actually invoking any targets or recording state. This is useful when porting an existing config — run it on a representative branch to confirm the new command selects the same targets the legacy manifest did.
Before — .aspect/workflows/config.yaml: 
tasks:
  - delivery:
      manifest_only: true
      rules:
        - condition:
            branches: [main]
After — CI configuration: 
on:
  push:
    branches: [main]

jobs:
  deliver:
    runs-on: aspect-workflows
    permissions:
      id-token: write
    env:
      ASPECT_API_TOKEN: ${{ secrets.ASPECT_API_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - name: Deliver (dry run)
        run: |
          aspect delivery \
            --query 'attr("tags", "deliverable", //...)' \
            --task:name delivery \
            --dry-run

​
Always deliver (--mode=always)

--mode=always disables change detection entirely and runs every resolved target. It’s the closest analogue to the legacy only_on_change: false behavior. Pair with --track-state=true (the default) on CI to record digests and deliveries — that way a subsequent --mode=selective run sees the up-to-date state. Pair with --track-state=false outside Aspect Workflows CI runners (local development, non-Aspect-Workflows CI) to skip both state tracking and the remote-cache requirement entirely. Common use cases:
  • Backfills and cache-invalidation events in CI, where every matching target should re-deliver regardless of change-detection state. Equivalent to listing every target in --force-target=… but in one flag, and the deliveries are still recorded: 
    aspect delivery \
  --query 'attr("tags", "deliverable", //...)' \
  --task:name delivery-backfill \
  --mode=always
  • Local testing of forced-delivery flows. Preview isn’t enough; you want to actually invoke each target on your machine. No remote cache, no state tracking: 
    aspect delivery \
  --query 'attr("tags", "deliverable", //tools/...)' \
  --task:name delivery-dev \
  --mode=always \
  --track-state=false
  • Adopting aspect delivery before a remote cache is provisioned. Run with --mode=always --track-state=false initially, then switch to --mode=selective once a remote cache and a state backend are wired up.
--mode=always runs every resolved target on every invocation. There is no skip path — if you point it at hundreds of targets you will deliver hundreds of targets, every time. Scope your --query carefully and be deliberate about when to invoke this mode in CI.

​
Break-glass forced re-delivery

Forced re-delivery bypasses change detection and re-delivers the target(s) even if their action digests have already been recorded. Use sparingly — typically only when a previous delivery partially succeeded and needs to be retried.
There are two break-glass paths: force a specific target (or set of targets), or force everything in scope.

​
Force everything (--mode=always)

When you want every resolved target re-delivered — backfills, cache-invalidation events, post-incident catch-up — pass --mode=always instead of enumerating each label. It skips change detection entirely while still recording the resulting deliveries (so the next --mode=selective run sees them): 
aspect delivery \
  --query 'attr("tags", "deliverable", //...)' \
  --task:name delivery-backfill \
  --mode=always
See Always deliver above for the full discussion of --mode=always.

​
Force specific targets (parameterized CI job)

The legacy ASPECT_WORKFLOWS_DELIVERY_TARGETS env var let users pick the target list at job-trigger time from a CI parameter field. The new aspect delivery accepts the same pattern via ASPECT_WORKFLOWS_DELIVERY_FORCE_TARGETS (whitespace-separated labels), which is merged with any --force-target flags. Wire your CI’s parameter input straight to that env var: 
on:
  workflow_dispatch:
    inputs:
      force_targets:
        description: "Bazel targets to force-deliver (space-separated). Leave empty for normal selective delivery."
        required: false
        default: ""

jobs:
  deliver:
    runs-on: aspect-workflows
    permissions:
      id-token: write
    env:
      ASPECT_API_TOKEN: ${{ secrets.ASPECT_API_TOKEN }}
      ASPECT_WORKFLOWS_DELIVERY_FORCE_TARGETS: ${{ inputs.force_targets }}
    steps:
      - uses: actions/checkout@v4
      - name: Deliver
        run: |
          aspect delivery \
            --query 'attr("tags", "deliverable", //...)' \
            --task:name delivery
To trigger a forced re-delivery, run the CI job from your provider’s UI and fill in the parameter field. An empty value falls through to normal selective delivery.
--force-target and ASPECT_WORKFLOWS_DELIVERY_FORCE_TARGETS are merged, so you can hard-code always-forced labels in --force-target=... and still let users append more from the CI parameter field at trigger time.
Force-target only flips the change-detection skip for labels already in the resolved delivery set (from --query or positional args). It does not add new labels. If a label passed via --force-target or ASPECT_WORKFLOWS_DELIVERY_FORCE_TARGETS isn’t present in the resolved set, aspect delivery hard-fails at startup so typos and stale labels are caught early. Update your --query or positional targets to include the label, or fix the typo.

​
Stamp and release-only flags

aspect delivery has two flags for passing Bazel flags, and the difference matters for change detection:
Flagconfig.axl argApplies toUse for
--release-bazel-flagrelease_bazel_flagsthe final delivery build only (phase 3)anything that adds non-determinism to release artifacts — --stamp, --workspace_status_command=<path>, and any --config that turns those on
--bazel-flagbazel_flagsevery build phase, including the change-detection digest phasesonly flags you’re certain don’t change outputs run-to-run — e.g. --jobs=100, --remote_cache=<uri>
Put --stamp, --workspace_status_command, and any --config that enables them in --release-bazel-flag (release_bazel_flags), not --bazel-flag (bazel_flags).The change-detection digest is computed from the build phases that --bazel-flag feeds. Stamping injects volatile values (commit SHA, build time, workspace status) into those phases, so the digest shifts on every commit — change detection then sees every target as new and re-delivers everything, every time, defeating selective delivery. --release-bazel-flag applies only to the final delivery build, after change detection has run, so stamped artifacts stay stamped without polluting the digest.This catches people via --config: a release config such as build:release --stamp --workspace_status_command=... in .bazelrc pulls stamping in the moment it’s activated. So --config=release typically belongs in --release-bazel-flag too — putting it in --bazel-flag re-introduces the exact problem. Only use --bazel-flag for a config you’ve confirmed adds no non-determinism.
The legacy stamp_flags list mapped to the delivery build, so it migrates to release_bazel_flags: Before — .aspect/workflows/config.yaml: 
tasks:
  - delivery:
      stamp_flags:
        - --stamp
        - --workspace_status_command=tools/bazel/workspace_status.sh
After — set once in .aspect/config.axl so every aspect delivery invocation picks it up:
.aspect/config.axl
def config(ctx: ConfigContext):
    ctx.tasks["delivery"].args.release_bazel_flags = [
        "--stamp",
        "--workspace_status_command=tools/bazel/workspace_status.sh",
    ]
release_bazel_flags defaults to ["--stamp"], so delivered binaries are stamped out of the box — you only need to set it to add a --workspace_status_command or other release-only flags, or to opt out with --release-bazel-flag=--nostamp. Assigning a new list replaces the default, so include --stamp in your list if you still want stamping.
A release --config usually pulls in stamping (e.g. build:release --stamp --workspace_status_command=...), so it belongs in release_bazel_flags — that applies it only to the final delivery build and keeps the volatile values out of the change-detection digest:
.aspect/config.axl
def config(ctx: ConfigContext):
    ctx.tasks["delivery"].args.release_bazel_flags = ["--config=release"]
Reserve bazel_flags for flags you’ve confirmed don’t change outputs run-to-run (e.g. --jobs, --remote_cache); those apply to every phase so change detection and the final build agree. Or pass either flag per invocation on the CLI when different delivery jobs need different flags (e.g. a release-only aspect delivery step alongside a default one): 
jobs:
  deliver:
    runs-on: aspect-workflows
    permissions:
      id-token: write
    env:
      ASPECT_API_TOKEN: ${{ secrets.ASPECT_API_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - name: Deliver
        run: |
          aspect delivery \
            --query 'attr("tags", "deliverable", //...)' \
            --task:name delivery \
            --release-bazel-flag=--config=release
If your --workspace_status_command only needs to run for stamped builds, you can also fold both into a .bazelrc config that a single --release-bazel-flag=--config=<name> activates:
.bazelrc
common:release-stamp --stamp --workspace_status_command=tools/bazel/workspace_status.sh
Then --release-bazel-flag=--config=release-stamp is enough — one place to maintain the list, and it stays on the release-only side so it never reaches the change-detection digest.

​
Salted change detection

The legacy salt_envs list mixed environment variable values into the Redis state key so that changing any of them would re-trigger delivery. The new --salt flag serves the same purpose — pass the concatenated values yourself.
Changing the salt invalidates all prior change-detection state for the given --task:name. Every target will be re-delivered on the next run. Pick salt sources that change only when you actually want a full re-delivery (e.g., a config version, not the current timestamp).
Before — .aspect/workflows/config.yaml: 
tasks:
  - delivery:
      auto_deliver: true
      salt_envs:
        - DEPLOY_ENV
        - FEATURE_FLAG_VERSION
      rules:
        - deliverable: 'attr("tags", "deliverable", //...)'
          condition:
            branches: [main]
After — CI configuration: 
on:
  push:
    branches: [main]

jobs:
  deliver:
    runs-on: aspect-workflows
    permissions:
      id-token: write
    env:
      ASPECT_API_TOKEN: ${{ secrets.ASPECT_API_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - name: Deliver
        env:
          DEPLOY_ENV: ${{ vars.DEPLOY_ENV }}
          FEATURE_FLAG_VERSION: ${{ vars.FEATURE_FLAG_VERSION }}
        run: |
          aspect delivery \
            --query 'attr("tags", "deliverable", //...)' \
            --task:name delivery \
            --salt="$DEPLOY_ENV:$FEATURE_FLAG_VERSION"

​
Preview without state tracking (--mode=always --dry-run --track-state=false)

For environments where the state backend isn’t available — local development machines, non-Aspect-Workflows CI, or anywhere ASPECT_WORKFLOWS_DELIVERY_API_ENDPOINT is not set — combine --mode=always with --dry-run --track-state=false. Nothing is recorded or queried, and no targets are run. 
aspect delivery \
  --query 'attr("tags", "deliverable", //...)' \
  --commit-sha="$(git rev-parse HEAD)" \
  --task:name delivery \
  --mode=always \
  --dry-run \
  --track-state=false
Every candidate appears as DRY-RUN, scoped by the same --task:name[:--salt] change-detection prefix you’d use in CI. If a remote cache is configured, action digests are computed and shown alongside each candidate — useful for verifying digest stability or sanity-checking your setup. If no remote cache is configured, the preview prints a NOTE and falls back to listing candidates without digests; everything else still works. The other combination tolerant of a missing remote cache is --mode=always --track-state=false (which actually runs targets, also without computing digests); every other mode needs digests for correctness.

​
Key behavioral differences

AreaYAML-configured tasksAspect CLI tasks
PipelineTwo tasks (manifest → delivery)Single command
State storeRedisBuilt-in state backend on Aspect Workflows CI runners
Hash sourceBazel output file hashRemote cache action digest
Branch/tag conditionsDeclared in .aspect/workflows/config.yamlHandled by CI script
ParallelismSequential by default--max-parallelization flag
Forced deliveryASPECT_WORKFLOWS_DELIVERY_TARGETS env var or only_on_change: false--force-target flag, ASPECT_WORKFLOWS_DELIVERY_FORCE_TARGETS env var, or --mode=always