# Repeatable builds

Keep the inputs needed to rebuild a bundle and understand why two builds may differ.

Source: https://debark.dev/docs/concepts/reproducibility

---
To repeat a build, you need more than the same command. The target snapshot, package versions,
configuration, input files, and build tools all affect the result.

For ordinary updates, use [refresh a bundle](/docs/operate/refreshing). This page is for keeping
a build record or comparing a later rebuild with an earlier one.

## Keep the build inputs

Save these together in a location appropriate for the snapshot’s contents:

- The target snapshot and package list.
- Any vendor .deb files and expected checksums.
- Configuration, policy, and approved archive-key files used by the build.
- The CLI version and source commit, available from `debark version`.
- The selected container image, if a container was used.
- The timestamp setting used for the build.

Keep private signing keys separately. The finished bundle and its `lock.json` preserve the
actual .deb files and versions selected.

## Fixing the clock with SOURCE_DATE_EPOCH

`SOURCE_DATE_EPOCH` sets the timestamp used for generated build metadata. Its value is a Unix
timestamp in seconds.

In Bash, when the package request is stored in a Git repository, you can use the commit time:

```bash
export SOURCE_DATE_EPOCH="$(git log -1 --pretty=%ct)"
debark build --snapshot target.tar.zst --list packages.txt \
  --out ./bundle --sign operator.key
```

Record the value for later builds. Debark also sorts generated entries and uses consistent
formatting for signed JSON documents.

Fixing the timestamp alone does not freeze the apt archive or package selection.

## Compare builds

Build into a new output directory when comparing results. An existing directory may contain
files retained from an earlier build.

Verify each bundle first:

```bash
debark verify ./bundle-a --key operator.pub
debark verify ./bundle-b --key operator.pub
sha256sum bundle-a/debark.manifest.json bundle-b/debark.manifest.json
```

Matching manifest checksums show that the manifest files match. Successful verification also
checks that the listed files match their recorded checksums.

If the manifests differ, compare `lock.json`, build settings, and package sources. A new
version in an apt archive, a changed snapshot, or different retained files can explain the
difference. Signature formats can also add their own metadata; comparing signatures alone
is not a comparison of package contents.

## Use the build record

`evidence.json` records build details. You can also capture progress events as the command runs:

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

Keep the event file when diagnosing a failed or unexpected build. It describes what happened
during that run and is not an independent verification of the build.

## Limits

Debark assembles packages built by their publishers. It does not rebuild those packages from
source or verify that the publisher’s own builds are reproducible.

A matching rebuild does not replace signature verification or a review of the software you
are installing. Reusing the same command against changing repositories can select new versions.

<NextSteps
  items={[
    {
      title: 'Run from a script',
      href: '/docs/guides/automation',
      description: 'Save results and handle failed builds.',
    },
    {
      title: 'Build records and SBOMs',
      href: '/docs/trust/sbom-and-evidence',
      description: 'Find package inventories and build information.',
    },
  ]}
/>