Public API

When consuming this module from CI, prefer Git source mode so Dagger clones the Rush repository internally. For a checked-out worktree, use the versioned rush-delivery-local launcher so exclusions apply before source transfer.

RUSH_DELIVERY_MODULE=github.com/BootstrapLaboratory/rush-delivery@v0.9.0

GitHub Actions can use the root action wrapper instead of assembling the raw command. See GitHub Action usage.

Entrypoints

workflow is the normal release orchestrator. It resolves source, validates metadata, computes the CI plan, builds selected deploy targets, packages their artifacts, deploys them in dependency order, and can compose selected package release targets.

dagger -m "$RUSH_DELIVERY_MODULE" call workflow \
  --git-sha="$GIT_SHA" \
  --event-name=push \
  --dry-run=false \
  --workflow-env-file="$WORKFLOW_ENV_FILE" \
  --deploy-env-file="$DEPLOY_ENV_FILE" \
  --release-targets-json='["npm"]' \
  --release-env-file="$RELEASE_ENV_FILE" \
  --runtime-files="$RUNTIME_FILES_DIR" \
  --source-mode=git \
  --source-repository-url="$SOURCE_REPOSITORY_URL" \
  --source-ref="$SOURCE_REF" \
  --source-auth-token-env=GITHUB_TOKEN

self-check is the framework health check. It runs the Dagger module typecheck and unit tests from this repository.

dagger call self-check

validate runs pull-request validation for affected Rush projects, target-specific validation metadata, and release-readiness checks when .dagger/release/npm.yaml is configured.

dagger -m "$RUSH_DELIVERY_MODULE" call validate \
  --git-sha="$GIT_SHA" \
  --event-name=pull_request \
  --pr-base-sha="$PR_BASE_SHA" \
  --deploy-env-file="$DEPLOY_ENV_FILE" \
  --toolchain-image-provider=github \
  --rush-cache-provider=github \
  --source-mode=git \
  --source-repository-url="$SOURCE_REPOSITORY_URL" \
  --source-ref="$SOURCE_REF" \
  --source-auth-token-env=GITHUB_TOKEN

For local validation against unpushed changes, use the bounded launcher from the local-copy guide.

releasePackages runs the package release/versioning flow from .dagger/release/npm.yaml. The first supported strategy is Rush change-file publishing for npm packages.

dagger -m "$RUSH_DELIVERY_MODULE" call release-packages \
  --git-sha="$GIT_SHA" \
  --dry-run=false \
  --release-env-file="$RELEASE_ENV_FILE" \
  --toolchain-image-provider=off \
  --rush-cache-provider=off \
  --source-mode=git \
  --source-repository-url="$SOURCE_REPOSITORY_URL" \
  --source-ref="$SOURCE_REF" \
  --source-auth-token-env=GITHUB_TOKEN

Live package releases require Git source mode with write credentials. Rush Delivery runs the shared Rush lifecycle in build-first order (build, lint, test, verify), lets Rush apply the change files, publishes packages, and pushes the version commit back to the configured target branch. Dry-runs run the same planning path without pushing commits, tags, or packages.

releasePackages uses a release-scoped metadata contract. It requires Rush project metadata and .dagger/release/npm.yaml, but it does not require deploy metadata. Rush cache provider metadata is only required when the selected Rush cache provider is not off.

The release env file must contain the npm token named by .dagger/release/npm.yaml and the Git token named by sourceAuthTokenEnv for live Git source releases.

See Entrypoints reference for every callable function, including separate detect, build, package, deploy, metadata validation, and diagnostic entrypoints.

Key Inputs

repo is the caller's Rush repository directory for sourceMode=local_copy. Git source mode does not require it. Existing top-level entrypoints keep their released static filter. localSource(repo) is the additive object used by the launcher after it has composed an already-filtered Directory; its constructor does not apply a second filter.

gitSha is the commit being validated or released. It is required for Git source mode.

eventName, forceTargetsJson, prBaseSha, and deployTagPrefix shape detection. Forced targets are used by manual deploy wrappers.

deployEnvFile is a newline-delimited environment file for workflow, validate, build, and deploy paths. The framework reads it once, then passes only package- or deploy-target-allowed variables to build and runtime containers. Application-image publishing may resolve the selected provider's public registry coordinates and protected registry/signing values from the workflow-plus-deploy overlay. Coordinate values remain ordinary routing data; credentials become Dagger secrets and neither class is projected to project code. Deploy receives only the packaged digest handoff.

workflowEnvFile is a newline-delimited environment file shared by the composed workflow. Use it for source/provider values that may be needed before a stage-specific overlay is selected. deployEnvFile and releaseEnvFile may repeat a workflow env key only with the same value.

releaseEnvFile is a newline-delimited environment file for package release. It carries package release credentials such as NPM_TOKEN. In the composed workflow, release metadata decides which values reach the package release container. In standalone releasePackages, the same file also carries source write credentials such as GITHUB_TOKEN.

releaseTargetsJson selects package release targets for workflow. Currently ["npm"] is supported. The default [] keeps deploy-only workflow behavior unchanged.

runtimeFiles is an optional directory of deploy-platform files such as cloud credentials, kubeconfig files, or generated deployment certificates. Deploy target metadata can mount files from this bundle without making them part of source, package artifacts, Rush install cache, or toolchain image hashes. Do not put OCI registry tokens, Cosign private keys, signing passwords, or Cosign public keys there; application-image credentials are Package-only environment inputs selected by provider metadata.

sourceMode is git or local_copy. Git mode is the recommended CI path and uses provider-neutral source coordinates. Local-copy mode needs repo and is intended for local tests, offline runs, and unpushed changes. The Action adds source-import-policy (bounded by default, legacy for recovery) and source-import-ignore-file. The portable launcher exposes equivalent flags.

toolchainImageProvider and rushCacheProvider are off by default. Provider github enables GHCR-backed toolchain images or Rush install cache. Optional .dagger/toolchains/rush.yaml extends the Rush workflow image with digest-pinned, checksummed executables. Its absence preserves the exact default toolchain identity. See the toolchain guide.

applicationImageProvider is off by default. A live selection containing an oci_image package target must choose a provider declared in .dagger/application-images/providers.yaml. Named-provider dry runs validate repository intent without requiring or resolving provider credentials. A supplied aggregate env file is still parsed for other configured capabilities; omit live OCI values from dry/no-OCI calls. Filesystem-only projects do not need the metadata or a configuration change after upgrading; when no selected target is OCI, workflow/package planning ignores the application provider input, provider file, and provider credentials. Provider coordinates may be static or selected by registry_env and repository_prefix_env. Named dry runs resolve only the public coordinate values; live credentials remain deferred until Package is ready. See the environment-profile tutorial.

For workflow, toolchainImagePolicy and rushCachePolicy default to lazy, which is the trusted release behavior: pull first, build or install on miss, and publish refreshed provider artifacts after success. For validate, both policies default to pull-or-build, which pulls existing artifacts and builds or installs locally on miss without publishing.

dockerSocket is an optional compatibility input for project-owned deploy targets that invoke Docker. First-class OCI package artifacts use Dagger-native build and publication and do not require it.

Defaults

Local defaults favor portability: provider-off, dry-run enabled, and local_copy source mode. CI should opt into provider adapters explicitly.

For OCI adoption, follow the OCI application images tutorial, then use the production guide, registry recipes, and troubleshooting guide.