Run Debark from a script

Use --json when a script needs command results. Use --json-events PATH when you also want a progress log. Always check the command’s exit code before using its output.

The commands below assume the CLI, required backend, snapshot, and signing keys are already available on the machine running the script.

For a baseline build, replace --snapshot target.tar.zst with --base ubuntu:24.04/minimal --arch amd64, adjusted for your target. No captured snapshot is needed.

You can work out your choices with the interactive CLI first, then use explicit options in your script. Keep any additional backend or policy settings with the printed command; --interactive itself requires a terminal.

Capture a build result

debark build --snapshot target.tar.zst --list packages.txt \
  --out ./bundle --sign operator.key --json > build.json

--json disables interactive prompts, colour, and progress bars. It cannot be combined with --interactive. If your request includes packages that need a redistribution acknowledgement, supply --acknowledge-redistribution after reviewing those requirements.

Pass --sign explicitly when signing is required. It makes a missing or unusable key a build failure. A build without a required signing key can otherwise produce an unsigned result.

Handle failed builds

Exit 0 means the command completed successfully. A nonzero code needs handling before a later step copies or uses the bundle.

For example, in Bash:

status=0
debark build --snapshot target.tar.zst --list packages.txt \
  --out ./bundle --sign operator.key --json > build.json || status=$?

case "$status" in
  0) echo "Build complete" ;;
  3) echo "Incomplete bundle: check failed inputs" >&2 ;;
  5) echo "apt could not satisfy the request" >&2 ;;
  6) echo "A policy rule blocked the build" >&2 ;;
  *) echo "Build failed with exit $status" >&2 ;;
esac
exit "$status"

Exit 3 means output was written but is incomplete. Other failures can also leave partial output or an older bundle at the same path. Treat only a successful current build as ready for transfer.

The exit-code reference lists all codes and suggested actions.

Record progress separately

debark build --snapshot target.tar.zst --list packages.txt \
  --out ./bundle --sign operator.key \
  --json --json-events build-events.ndjson > build.json

The event file is NDJSON: one JSON object per line. Keep it when troubleshooting a build that failed before it wrote a bundle. Use type and structured attributes for automation; msg is text intended for people.

--json-events - sends events to stdout. Use a separate event file when stdout is already being captured as a single JSON result.

Example build-and-check script

This Bash script stops on failures and saves the result and diagnostic files. SIGNING_KEY and VERIFY_KEY must be paths to an existing key pair, with the public key outside the output bundle.

#!/usr/bin/env bash
set -euo pipefail

: "${SIGNING_KEY:?Set the private key path}"
: "${VERIFY_KEY:?Set the trusted public key path}"
mkdir -p reports

debark build --snapshot target.tar.zst --list packages.txt \
  --out ./bundle --sign "$SIGNING_KEY" --sbom \
  --json --json-events reports/build.ndjson > reports/build.json

debark verify ./bundle --key "$VERIFY_KEY" --json > reports/verify.json
jq -e '.ok and .signed' reports/verify.json > /dev/null

debark doctor ./bundle --json > reports/doctor.json
echo "Build and verification completed; review reports/doctor.json."

Doctor warnings do not produce a failing exit code. If a condition must block a build, use an appropriate policy rule or explicitly check the findings.

Reuse settings and downloads

Use a configuration profile for repeated backend, policy, and key settings. Select it with --profile NAME or DEBARK_PROFILE.

Keep the configured store directory between CI jobs to reuse downloads. An empty runner cache means files must be fetched again.

For build comparisons, save the snapshot, request, tool version, and other inputs. SOURCE_DATE_EPOCH fixes generated timestamps; it does not freeze remote package repositories. See repeatable builds.