Skip to content

entrypoints.md

Latest commit

 

History

History
292 lines (220 loc) · 9.66 KB

entrypoints.md

File metadata and controls

292 lines (220 loc) · 9.66 KB
Raw

Entrypoints Reference

When consuming this module from CI, prefer Git source mode so Dagger clones the Rush repository internally:

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

workflow

The main release composition. It resolves source, validates metadata, detects deploy targets, selects explicit package release targets, builds, packages, and then runs deploy and package-release side effects.

Use it for normal CI release runs and local release dry-runs.

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

When release-targets-json is empty, returns the existing text deployment summary. When package release targets are selected, returns a combined summary with deploy and release_packages sections.

Deploy and package release side effects run after shared prerequisites. They can run concurrently and are not transactional across external systems.

For local runs against a checked-out working tree, use rush-delivery-local from the bounded local-copy guide.

validate

Runs Dagger-owned validation for affected Rush projects. It can also run target-specific validation metadata such as backing services, migrations, server startup, and smoke tests.

Use it for pull-request validation paths or local validation experiments.

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

Returns a validation summary.

For local runs against a checked-out working tree, use rush-delivery-local from the bounded local-copy guide.

release-packages

Runs package release/versioning from .dagger/release/npm.yaml. The initial strategy is npm publishing through Rush change files.

Use it for standalone package release workflows, package-only repositories, and release debugging. The entrypoint runs the shared Rush lifecycle in build-first order (build, lint, test, verify), lets Rush apply change files, publishes packages, and pushes the generated version commit. For live releases, Rush Delivery prepares the metadata target branch locally before rush publish so Rush can check it out for the final merge. It does not touch deploy tags.

NPM provenance defaults to false; opt in from .dagger/release/npm.yaml only when the release runtime is wired for supported npm provenance detection.

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

Use toolchain-image-provider=github or rush-cache-provider=github only when the repository has matching provider metadata and the CI job has package registry permissions.

For local dry-runs against a checked-out working tree, use rush-delivery-local ... -- release-packages and keep --dry-run=true.

local-source

Returns an additive Dagger object with workflow, validate, and release-packages functions over a caller-composed repo Directory. It is the module boundary used by rush-delivery-local and the bounded GitHub Action path. The constructor applies no static ignores, so ordered caller re-inclusions survive.

repo=$(host | directory /workspace/project --exclude='**/node_modules')
local-source --repo=$repo | validate --event-name=pull_request

The snippet is Dagger Shell, not a host shell. Prefer the release launcher, which validates and quotes paths/patterns and verifies .git, .dagger, and rush.json before delegating. The old top-level functions remain the legacy-compatible direct-call API.

detect

Computes the canonical CI plan JSON. The plan includes mode, validation targets, deploy targets, and affected projects by deploy target.

Use it when a CI provider intentionally runs split stages. The workflow entrypoint already calls it internally.

dagger -m "$RUSH_DELIVERY_MODULE" call detect \
  --repo=. \
  --event-name=push \
  --force-targets-json='[]' \
  --deploy-tag-prefix=deploy/prod

Returns JSON intended for Dagger stage handoff.

build-deploy-targets

Runs the generic Rush build stage for deploy targets selected by a CI plan file.

Use it only in split-stage workflows where build is separated from package and deploy.

dagger -m "$RUSH_DELIVERY_MODULE" call build-deploy-targets \
  --repo=. \
  --ci-plan-file="$CI_PLAN_FILE" \
  --deploy-env-file="$DEPLOY_ENV_FILE"

Returns a Dagger directory containing the built workspace. deploy-env-file is optional, but required when selected package targets declare build-time pass_env or map_env values without dry-run defaults. Pass --dry-run=true when you want build-time env to use package target dry_run_defaults.

package-deploy-targets

Materializes deploy artifacts for targets selected by a CI plan file. Package behavior is driven by .dagger/package/targets.

Use it only in split-stage workflows after build outputs already exist. Treat that built directory and its provider/deploy metadata as trusted Package input: this entrypoint can freeze only the credential-name boundary present when it is invoked. Prefer build-and-package-deploy-targets when Build could modify metadata, because the combined producer captures the boundary before Build.

dagger -m "$RUSH_DELIVERY_MODULE" call package-deploy-targets \
  --repo=. \
  --ci-plan-file="$CI_PLAN_FILE" \
  --artifact-prefix=deploy-target \
  --git-sha="$GIT_SHA" \
  --source-repository-url="$SOURCE_REPOSITORY_URL" \
  --dry-run=false \
  --deploy-env-file="$DEPLOY_ENV_FILE" \
  --application-image-provider=off

Returns a Dagger directory containing packaged artifacts, a package manifest, and OCI evidence when selected. It accepts the same build-time deploy-env-file and dry-run inputs as build-deploy-targets. OCI targets also use git-sha, the optional source URL, and the selected application-image provider. Directory/archive-only calls remain valid without those additions.

build-and-package-deploy-targets

Runs build and package as separate logical stages, then exports the final packaged workspace once.

Use it when a split workflow needs build and package together but deploy later.

dagger -m "$RUSH_DELIVERY_MODULE" call build-and-package-deploy-targets \
  --repo=. \
  --ci-plan-file="$CI_PLAN_FILE" \
  --artifact-prefix=deploy-target \
  --deploy-env-file="$DEPLOY_ENV_FILE" \
  --git-sha="$GIT_SHA" \
  --source-repository-url="$SOURCE_REPOSITORY_URL" \
  --application-image-provider=off

Returns a Dagger directory containing packaged artifacts and a package manifest. For OCI targets, Package performs registry publication and carries the verified manifest/evidence into the returned directory; Deploy later resolves the image from the registry by digest.

The commands above are filesystem-first examples. For a live OCI target, configure the package target and application-image provider together, then replace off with that provider name. Follow the OCI application images tutorial before using the lower-level split-stage APIs.

deploy-release

Deploys selected targets from an already packaged workspace. It executes deploy targets in service-mesh wave order and can use a package manifest to resolve artifact paths.

Use it for split-stage workflows, deploy-only retries, or tests around deploy metadata.

dagger -m "$RUSH_DELIVERY_MODULE" call deploy-release \
  --repo=. \
  --git-sha="$GIT_SHA" \
  --release-targets-json='["server","webapp"]' \
  --environment=prod \
  --dry-run=false \
  --deploy-env-file="$DEPLOY_ENV_FILE" \
  --runtime-files="$RUNTIME_FILES_DIR" \
  --package-manifest-file="$PACKAGE_MANIFEST_FILE"

Returns a text deployment summary.

self-check

Runs the framework health check: Dagger module typecheck and unit tests.

Use it before changing framework source, schemas, or docs.

dagger call self-check

Returns a self-check summary.

validate-metadata-contract

Checks cross-file metadata consistency without running release stages.

Use it when editing .dagger/ metadata and wanting a fast contract check.

dagger -m "$RUSH_DELIVERY_MODULE" call validate-metadata-contract --repo=.

Returns formatted metadata contract JSON.

describe-release-targets

Validates and normalizes a release target JSON array.

Use it for quick checks around manual target input.

dagger -m "$RUSH_DELIVERY_MODULE" call describe-release-targets \
  --release-targets-json='["server"]'

Returns a short text description.

For OCI-specific package/deploy behavior, use the production guide, registry recipes, and troubleshooting guide.

ping

Returns a simple readiness marker.

Use it only to verify that the module is callable.

dagger -m "$RUSH_DELIVERY_MODULE" call ping