aspect delivery - Aspect Build

Rosetta’s delivery system (Workflows 5.x) 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 these 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={false,true,build} (default false; bare --dry-run means true): true prints what would be delivered and skips the final delivery build, so nothing is stamped and no release artifact is materialized. build previews and runs that build — the only way to get the manifest’s on-disk paths (entrypoint_path, runfiles_dir, runfiles_workspace_dir, default_outputs, all empty under true) and the “never built” / “not runnable” checks. Migrating a Rosetta manifest_only: true that consumed those paths wants build, not true.
--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, which host the state backend.

This migration only affects how delivery is triggered and tracked. The delivery targets themselves (bazel run-able rules tagged deliverable) don’t need to change.

The flags compose:

Combination	Behavior	Prerequisites
`--mode=selective` (default)	selective; runs candidates; records state	state backend, remote cache
`--mode=selective --dry-run`	selective preview; records digests for future runs; no run	state backend, remote cache
`--mode=always`	runs every target; records digests + deliveries	state backend, remote cache
`--mode=always --dry-run`	always preview; records digests; no run	state backend, remote cache
`--mode=always --track-state=false`	runs every target; nothing recorded; no digests computed	none
`--mode=always --dry-run --track-state=false`	best-effort preview without state tracking; nothing recorded; no run	remote cache (optional; without it the preview lists candidates without digests)
`--mode=selective --track-state=false` (any `--dry-run`)	invalid: selective delivery requires state	—

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 hasn’t 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’s stable across machines and rebuild attempts. Two runners producing bit-identical outputs derive the same digest, so change detection skips the second delivery.

Always set —task:name explicitly. Without it the change-detection prefix is derived from the CI job name, so renaming the job shifts the scope and re-delivers every target, and the shards of a GitHub Actions matrix share one scope. Off CI the name is random per run. Pick a stable identifier for your pipeline (e.g. delivery, production-deploy) and reuse it across runs.

Requirements

The combination table lists the prerequisites per invocation. In short:

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.

What changed

Area	YAML-configured tasks	Aspect CLI tasks
Invocation	`rosetta 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, so pass it as `--release-bazel-flag=--config=release` instead.
Salt	`salt_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-only	`manifest_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 filter	`condition: { branches: [...] }`	run `aspect delivery` only from the relevant CI branch step
Tag filter	`condition: { tags: [...] }`	run `aspect delivery` only from the relevant CI tag step
Limit query	`limit_query`	not needed: scope the `--query` expression directly
State store	`redis_url` / `redis_use_tls`	not applicable (the state backend replaces Redis)
Trigger	`auto_deliver: true`	not applicable: calling `aspect delivery` is itself the trigger
Workspaces	`workspaces:` top-level list	not 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.

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: [self-hosted, aspect-workflows, aspect-default]
    permissions:
      contents: read    # actions/checkout
      id-token: write   # artifact uploads and the PR summary comment
    steps:
      - uses: actions/checkout@v6
      - uses: aspect-build/setup-aspect@ebca96eb49ef58c00d4226de8bd3a0813507dd87 # v2026.38.3
        with:
          aspect-api-token: ${{ secrets.ASPECT_API_TOKEN }}
      - name: Deliver
        run: |
          aspect delivery \
            --ci-host=gh \
            --query 'attr("tags", "deliverable", //...)' \
            --task:name delivery

steps:
  - label: ":rocket: Deliver"
    if: build.branch == "main"
    plugins:
      - aspect-build/setup-aspect#8de9aed254d0699baf201f66e2076fc8c09f42b9: ~ # v2026.38.2
    command: |
      aspect delivery \
        --query 'attr("tags", "deliverable", //...)' \
        --task:name delivery
    secrets:
      - ASPECT_API_TOKEN
    agents:
      queue: aspect-default

include:
  - component: $CI_SERVER_FQDN/aspect-build/setup-aspect-gitlab-component/setup@2026.38.3

deliver:
  extends: .setup-aspect
  tags:
    - aspect-workflows
    - aspect-default
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
  script:
    - |
      aspect delivery \
        --ci-host=gl \
        --query 'attr("tags", "deliverable", //...)' \
        --task:name delivery
# Set ASPECT_API_TOKEN as a masked CI/CD variable in Settings → CI/CD → Variables.

orbs:
  setup-aspect: aspect-build/setup-aspect@2026.38.2

jobs:
  deliver:
    machine: true
    resource_class: YOUR-ORG/aspect-default
    steps:
      - checkout
      - setup-aspect/setup
      - run:
          name: Deliver
          command: |
            aspect delivery \
              --ci-host=circle \
              --query 'attr("tags", "deliverable", //...)' \
              --task:name delivery

workflows:
  delivery:
    jobs:
      - deliver:
          filters:
            branches:
              only: main
# Set ASPECT_API_TOKEN as a project environment variable or context secret.

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: [self-hosted, aspect-workflows, aspect-default]
    permissions:
      contents: read    # actions/checkout
      id-token: write   # artifact uploads and the PR summary comment
    steps:
      - uses: actions/checkout@v6
      - uses: aspect-build/setup-aspect@ebca96eb49ef58c00d4226de8bd3a0813507dd87 # v2026.38.3
        with:
          aspect-api-token: ${{ secrets.ASPECT_API_TOKEN }}

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

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

steps:
  - label: ":rocket: Deliver services (branch)"
    if: build.branch == "main" || build.branch =~ /^hotfix\//
    plugins:
      - aspect-build/setup-aspect#8de9aed254d0699baf201f66e2076fc8c09f42b9: ~ # v2026.38.2
    command: |
      aspect delivery \
        --query 'set(//services/...)' \
        --task:name delivery
    secrets:
      - ASPECT_API_TOKEN
    agents:
      queue: aspect-default

  - label: ":rocket: Deliver release (tag)"
    if: build.tag =~ /^v[0-9]+\.[0-9]+\.[0-9]+$$/
    plugins:
      - aspect-build/setup-aspect#8de9aed254d0699baf201f66e2076fc8c09f42b9: ~ # v2026.38.2
    command: |
      aspect delivery \
        //tools:release \
        --task:name delivery
    secrets:
      - ASPECT_API_TOKEN
    agents:
      queue: aspect-default

include:
  - component: $CI_SERVER_FQDN/aspect-build/setup-aspect-gitlab-component/setup@2026.38.3

deliver-branch:
  extends: .setup-aspect
  tags:
    - aspect-workflows
    - aspect-default
  rules:
    - if: '$CI_COMMIT_BRANCH == "main" || $CI_COMMIT_BRANCH =~ /^hotfix\//'
  script:
    - |
      aspect delivery \
        --ci-host=gl \
        --query 'set(//services/...)' \
        --task:name delivery

deliver-tag:
  extends: .setup-aspect
  tags:
    - aspect-workflows
    - aspect-default
  rules:
    - if: '$CI_COMMIT_TAG =~ /^v[0-9]+\.[0-9]+\.[0-9]+$/'
  script:
    - |
      aspect delivery \
        --ci-host=gl \
        //tools:release \
        --task:name delivery
# Set ASPECT_API_TOKEN as a masked CI/CD variable in Settings → CI/CD → Variables.

version: 2.1

orbs:
  setup-aspect: aspect-build/setup-aspect@2026.38.2

jobs:
  deliver-branch:
    machine: true
    resource_class: YOUR-ORG/aspect-default
    steps:
      - checkout
      - setup-aspect/setup
      - run:
          name: Deliver services
          command: |
            aspect delivery \
              --ci-host=circle \
              --query 'set(//services/...)' \
              --task:name delivery

  deliver-tag:
    machine: true
    resource_class: YOUR-ORG/aspect-default
    steps:
      - checkout
      - setup-aspect/setup
      - run:
          name: Deliver release
          command: |
            aspect delivery \
              --ci-host=circle \
              //tools:release \
              --task:name delivery

workflows:
  delivery:
    jobs:
      - deliver-branch:
          filters:
            branches:
              only: [main, /hotfix\/.*/]
            tags:
              ignore: /.*/
      - deliver-tag:
          filters:
            branches:
              ignore: /.*/
            tags:
              only: /^v[0-9]+\.[0-9]+\.[0-9]+$/
# Set ASPECT_API_TOKEN as a project environment variable or context secret.

Dry-run / manifest-only mode

Use —dry-run to preview what would be delivered without running any targets. It still records target digests with the state backend but marks nothing delivered, so the next real run delivers the same set. 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: [self-hosted, aspect-workflows, aspect-default]
    permissions:
      contents: read    # actions/checkout
      id-token: write   # artifact uploads and the PR summary comment
    steps:
      - uses: actions/checkout@v6
      - uses: aspect-build/setup-aspect@ebca96eb49ef58c00d4226de8bd3a0813507dd87 # v2026.38.3
        with:
          aspect-api-token: ${{ secrets.ASPECT_API_TOKEN }}
      - name: Deliver (dry run)
        run: |
          aspect delivery \
            --ci-host=gh \
            --query 'attr("tags", "deliverable", //...)' \
            --task:name delivery \
            --dry-run

steps:
  - label: ":rocket: Deliver (dry run)"
    if: build.branch == "main"
    plugins:
      - aspect-build/setup-aspect#8de9aed254d0699baf201f66e2076fc8c09f42b9: ~ # v2026.38.2
    command: |
      aspect delivery \
        --query 'attr("tags", "deliverable", //...)' \
        --task:name delivery \
        --dry-run
    secrets:
      - ASPECT_API_TOKEN
    agents:
      queue: aspect-default

include:
  - component: $CI_SERVER_FQDN/aspect-build/setup-aspect-gitlab-component/setup@2026.38.3

deliver:
  extends: .setup-aspect
  tags:
    - aspect-workflows
    - aspect-default
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
  script:
    - |
      aspect delivery \
        --ci-host=gl \
        --query 'attr("tags", "deliverable", //...)' \
        --task:name delivery \
        --dry-run
# Set ASPECT_API_TOKEN as a masked CI/CD variable in Settings → CI/CD → Variables.

orbs:
  setup-aspect: aspect-build/setup-aspect@2026.38.2

jobs:
  deliver:
    machine: true
    resource_class: YOUR-ORG/aspect-default
    steps:
      - checkout
      - setup-aspect/setup
      - run:
          name: Deliver (dry run)
          command: |
            aspect delivery \
              --ci-host=circle \
              --query 'attr("tags", "deliverable", //...)' \
              --task:name delivery \
              --dry-run

workflows:
  delivery:
    jobs:
      - deliver:
          filters:
            branches:
              only: main
# Set ASPECT_API_TOKEN as a project environment variable or context secret.

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, so 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.

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. See Always deliver.

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: [self-hosted, aspect-workflows, aspect-default]
    permissions:
      contents: read    # actions/checkout
      id-token: write   # artifact uploads and the PR summary comment
    env:
      ASPECT_WORKFLOWS_DELIVERY_FORCE_TARGETS: ${{ inputs.force_targets }}
    steps:
      - uses: actions/checkout@v6
      - uses: aspect-build/setup-aspect@ebca96eb49ef58c00d4226de8bd3a0813507dd87 # v2026.38.3
        with:
          aspect-api-token: ${{ secrets.ASPECT_API_TOKEN }}
      - name: Deliver
        run: |
          aspect delivery \
            --ci-host=gh \
            --query 'attr("tags", "deliverable", //...)' \
            --task:name delivery

steps:
  # Gate the input on UI-triggered builds so webhook/scheduled builds
  # aren't blocked. On non-UI builds the input step is skipped, the
  # meta-data fetch below returns the default empty string, and delivery
  # runs in normal selective mode.
  - key: force_targets_block
    if: build.source == "ui"
    input: ":aspect-build: Force-delivery parameters"
    fields:
      - text: FORCE_TARGETS
        hint: "Space-separated Bazel labels to force-deliver. Example: `//app/a:push_release //app/b:push_release`. Leave empty for normal selective delivery."
        required: false
        default: ""
        key: force_targets
        # Validate the input against Bazel's label grammar so a typo
        # is caught at job-trigger time rather than during the build.
        # Allows whitespace (including empty), one or more labels, and
        # the full label syntax — repository, package path, and target name.
        format: ^\s*$|^\s*(?:([@]{1,2}[\w.~-]*|[@]{0})\/\/(?:[\w.@-]+\/)*[\w.@-]*(?::(?:[\w\[\]!%@^"#\$&'()*+,;<=>?{|}~.-]+\/)*[\w\[\]!%@^"#\$&'()*+,;<=>?{|}~.-]*)?(?!\/)(?:\s+)?)+\s*$

  - label: ":rocket: Deliver"
    depends_on:
      # Per-dep allow_failure so a skipped input on non-UI builds doesn't
      # bypass real failures from other dependencies (add them above).
      - step: force_targets_block
        allow_failure: true
    plugins:
      - aspect-build/setup-aspect#8de9aed254d0699baf201f66e2076fc8c09f42b9: ~ # v2026.38.2
    command: |
      export ASPECT_WORKFLOWS_DELIVERY_FORCE_TARGETS=$(buildkite-agent meta-data get force_targets --default '')
      aspect delivery \
        --query 'attr("tags", "deliverable", //...)' \
        --task:name delivery
    secrets:
      - ASPECT_API_TOKEN
    agents:
      queue: aspect-default

include:
  - component: $CI_SERVER_FQDN/aspect-build/setup-aspect-gitlab-component/setup@2026.38.3

deliver:
  extends: .setup-aspect
  tags:
    - aspect-workflows
    - aspect-default
  rules:
    - if: $CI_PIPELINE_SOURCE == "web"     # GitLab "Run pipeline" UI exposes FORCE_TARGETS as an input
    - if: $CI_PIPELINE_SOURCE == "push"
  variables:
    ASPECT_WORKFLOWS_DELIVERY_FORCE_TARGETS: $FORCE_TARGETS
  script:
    - |
      aspect delivery \
        --ci-host=gl \
        --query 'attr("tags", "deliverable", //...)' \
        --task:name delivery
# Declare FORCE_TARGETS as a pipeline variable in Settings → CI/CD → Variables
# (Type: Variable, default empty) so it appears as an editable field on the
# "Run pipeline" page.
# Set ASPECT_API_TOKEN as a masked CI/CD variable in Settings → CI/CD → Variables.

version: 2.1

orbs:
  setup-aspect: aspect-build/setup-aspect@2026.38.2

parameters:
  force_targets:
    type: string
    default: ""
    description: "Bazel targets to force-deliver (space-separated). Leave empty for normal selective delivery."

jobs:
  deliver:
    machine: true
    resource_class: YOUR-ORG/aspect-default
    environment:
      ASPECT_WORKFLOWS_DELIVERY_FORCE_TARGETS: << pipeline.parameters.force_targets >>
    steps:
      - checkout
      - setup-aspect/setup
      - run:
          name: Deliver
          command: |
            aspect delivery \
              --ci-host=circle \
              --query 'attr("tags", "deliverable", //...)' \
              --task:name delivery

workflows:
  delivery:
    jobs: [deliver]
# Set ASPECT_API_TOKEN as a project environment variable or context secret.

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 doesn’t 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

Which flag carries a Bazel flag matters for change detection:

Flag	`config.axl` arg	Applies to	Use for
`--release-bazel-flag`	`release_bazel_flags`	the final delivery build only	anything that adds non-determinism to release artifacts: `--stamp`, `--workspace_status_command=<path>`, and any `--config` that turns those on
`--bazel-flag`	`bazel_flags`	every build phase, including the change-detection digest phases	only flags you’re certain don’t change outputs run-to-run, e.g. `--jobs=100`, `--remote_cache=<uri>`

Stamping through --bazel-flag shifts the change-detection digest on every commit, so every target re-delivers every time. See Stamping and Bazel flags for why, including the --config=release case. 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, which 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"]

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: [self-hosted, aspect-workflows, aspect-default]
    permissions:
      contents: read    # actions/checkout
      id-token: write   # artifact uploads and the PR summary comment
    steps:
      - uses: actions/checkout@v6
      - uses: aspect-build/setup-aspect@ebca96eb49ef58c00d4226de8bd3a0813507dd87 # v2026.38.3
        with:
          aspect-api-token: ${{ secrets.ASPECT_API_TOKEN }}
      - name: Deliver
        run: |
          aspect delivery \
            --ci-host=gh \
            --query 'attr("tags", "deliverable", //...)' \
            --task:name delivery \
            --release-bazel-flag=--config=release

steps:
  - label: ":rocket: Deliver"
    plugins:
      - aspect-build/setup-aspect#8de9aed254d0699baf201f66e2076fc8c09f42b9: ~ # v2026.38.2
    command: |
      aspect delivery \
        --query 'attr("tags", "deliverable", //...)' \
        --task:name delivery \
        --release-bazel-flag=--config=release
    secrets:
      - ASPECT_API_TOKEN
    agents:
      queue: aspect-default

include:
  - component: $CI_SERVER_FQDN/aspect-build/setup-aspect-gitlab-component/setup@2026.38.3

deliver:
  extends: .setup-aspect
  tags:
    - aspect-workflows
    - aspect-default
  script:
    - |
      aspect delivery \
        --ci-host=gl \
        --query 'attr("tags", "deliverable", //...)' \
        --task:name delivery \
        --release-bazel-flag=--config=release
# Set ASPECT_API_TOKEN as a masked CI/CD variable in Settings → CI/CD → Variables.

orbs:
  setup-aspect: aspect-build/setup-aspect@2026.38.2

jobs:
  deliver:
    machine: true
    resource_class: YOUR-ORG/aspect-default
    steps:
      - checkout
      - setup-aspect/setup
      - run:
          name: Deliver
          command: |
            aspect delivery \
              --ci-host=circle \
              --query 'attr("tags", "deliverable", //...)' \
              --task:name delivery \
              --release-bazel-flag=--config=release
# Set ASPECT_API_TOKEN as a project environment variable or context secret.

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: [self-hosted, aspect-workflows, aspect-default]
    permissions:
      contents: read    # actions/checkout
      id-token: write   # artifact uploads and the PR summary comment
    steps:
      - uses: actions/checkout@v6
      - uses: aspect-build/setup-aspect@ebca96eb49ef58c00d4226de8bd3a0813507dd87 # v2026.38.3
        with:
          aspect-api-token: ${{ secrets.ASPECT_API_TOKEN }}
      - name: Deliver
        env:
          DEPLOY_ENV: ${{ vars.DEPLOY_ENV }}
          FEATURE_FLAG_VERSION: ${{ vars.FEATURE_FLAG_VERSION }}
        run: |
          aspect delivery \
            --ci-host=gh \
            --query 'attr("tags", "deliverable", //...)' \
            --task:name delivery \
            --salt="$DEPLOY_ENV:$FEATURE_FLAG_VERSION"

steps:
  - label: ":rocket: Deliver"
    if: build.branch == "main"
    plugins:
      - aspect-build/setup-aspect#8de9aed254d0699baf201f66e2076fc8c09f42b9: ~ # v2026.38.2
    command: |
      aspect delivery \
        --query 'attr("tags", "deliverable", //...)' \
        --task:name delivery \
        --salt="$$DEPLOY_ENV:$$FEATURE_FLAG_VERSION"
    secrets:
      - ASPECT_API_TOKEN
    agents:
      queue: aspect-default

include:
  - component: $CI_SERVER_FQDN/aspect-build/setup-aspect-gitlab-component/setup@2026.38.3

deliver:
  extends: .setup-aspect
  tags:
    - aspect-workflows
    - aspect-default
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
  script:
    - |
      aspect delivery \
        --ci-host=gl \
        --query 'attr("tags", "deliverable", //...)' \
        --task:name delivery \
        --salt="$DEPLOY_ENV:$FEATURE_FLAG_VERSION"
# Set ASPECT_API_TOKEN as a masked CI/CD variable in Settings → CI/CD → Variables.

orbs:
  setup-aspect: aspect-build/setup-aspect@2026.38.2

jobs:
  deliver:
    machine: true
    resource_class: YOUR-ORG/aspect-default
    steps:
      - checkout
      - setup-aspect/setup
      - run:
          name: Deliver
          command: |
            aspect delivery \
              --ci-host=circle \
              --query 'attr("tags", "deliverable", //...)' \
              --task:name delivery \
              --salt="$DEPLOY_ENV:$FEATURE_FLAG_VERSION"
# Set ASPECT_API_TOKEN as a project environment variable or context secret.

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 isn’t 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, for verifying digest stability or sanity-checking your setup. If no remote cache is configured, the preview prints a NOTE and lists candidates without digests.

Key behavioral differences

Area	YAML-configured tasks	Aspect CLI tasks
Pipeline	Two tasks (manifest → delivery)	Single command
State store	Redis	Built-in state backend on Aspect Workflows CI runners
Hash source	Bazel output file hash	Remote cache action digest
Branch/tag conditions	Declared in `.aspect/workflows/config.yaml`	Handled by CI script
Parallelism	Sequential by default	`--max-parallelization` flag
Forced delivery	`ASPECT_WORKFLOWS_DELIVERY_TARGETS` env var or `only_on_change: false`	`--force-target` flag, `ASPECT_WORKFLOWS_DELIVERY_FORCE_TARGETS` env var, or `--mode=always`

​What determines “needs delivery”

​Requirements

​What changed

​Examples

​Query-based delivery on main

​Multi-condition rules (branches and tags)

​Dry-run / manifest-only mode

​Always deliver (--mode=always)

​Break-glass forced re-delivery

​Force everything (--mode=always)

​Force specific targets (parameterized CI job)

​Stamp and release-only flags

​Salted change detection

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

​Key behavioral differences

What determines “needs delivery”

Requirements

What changed

Examples

Query-based delivery on main

Multi-condition rules (branches and tags)

Dry-run / manifest-only mode

Always deliver (`--mode=always`)

Break-glass forced re-delivery

Force everything (`--mode=always`)

Force specific targets (parameterized CI job)

Stamp and release-only flags

Salted change detection

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

Key behavioral differences