A consumer checks out the tag of your SDK, runs the build, and gets a tarball whose SHA-256 is not the one on npm. Nothing on the release says which generator, compiler, or packaging step made the published file, so the package is a binary nobody but your CI can vouch for.
What you get
You will end up with two clean builds of one commit, a hash comparison of what each would publish, and a tool that names the varying field when the hashes differ. This is for you if you publish generated SDKs and want consumers to rebuild them.
Short answer
Pin the generator, the toolchain, and the lockfiles, record them beside the release, and build
the commit twice in empty directories. Compare the tarball hashes, and the h1 hash for a Go
module. Two sdkgen builds a minute apart gave byte-identical npm tarballs and Go trees, and so
did Hey API’s client. A mismatch is most often the packaging step: plain tar records each
file’s modification time.
You will need
An SDK generated from an OpenAPI 3 document, Node 22 or later, and GNU tar and gzip, which
pack.mjs runs. The document here is the five-operation Bookshelf API. record.sh made the two
builds and ran diffoscope once, and the page’s commands read what it
committed under builds/, so nothing is generated or downloaded when they run.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
diffoscope on a mismatch | Two artifacts differ and you need the field that moved | A Python tool whose site advises installing external tools for meaningful results, all in your CI image | The hashes already match |
Fern fern.config.json and generatorVersion pins | Fern generates the SDK and you pin the CLI and every target’s generator | Self-hosted generation is an Enterprise feature, so a build on a runner you own needs that plan | You want both builds on runners you own |
| Hey API exact version pin | A TypeScript client from @hey-api/openapi-ts, pinned with -E | Its postProcess tools run from your project, so their versions are inputs too | You need clients in more than TypeScript |
| npm provenance attestation | You publish from GitHub Actions or GitLab CI/CD and want the source commit on the package | It names the build, but proves nothing about whether a rebuild matches | A consumer wants to rebuild and compare |
| sdkgen deterministic generation | An sdkgen SDK, where one model feeds a TypeScript and a Go target | Ranges in the generated ts/package.json, so the compiler floats until you commit a lockfile | A generator you already run passes the same check |
Voxgig maintains sdkgen, one of the five rows in the table, and this page does not rank it over the other four.
Pins and an attestation record what a build should use, and the two-build hash shows what it
produced. The pins are cheap and come first. diffoscope costs an install and earns it on the first mismatch.
Provenance pairs well with all of them, and replaces none.
Build the same commit twice from empty directories
record.sh runs each build in a fresh temporary directory, a minute apart, so the files of the
second build carry other modification times. The generator and the client generator are pinned on the command
line, and .sdk/package-lock.json, which the scaffold writes, pins the toolchain behind them.
npx --yes @voxgig/create-sdkgen@0.31.9 bookshelf --def api.json --target ts --target go > scaffold.log 2>&1
(cd bookshelf-sdk/.sdk && npm ci --no-audit --no-fund > /dev/null 2>&1 && npm run generate > /dev/null 2>&1)
(cd bookshelf-sdk/ts && npm install --no-audit --no-fund > /dev/null 2>&1 && npm run build > /dev/null 2>&1)
(cd bookshelf-sdk/ts && npm pack --silent --pack-destination "$dir" > /dev/null)
npx --yes -p typescript@5.9.3 -p @hey-api/openapi-ts@0.99.0 openapi-ts -i api.json -o heyapi > /dev/null 2>&1
Each build also writes the versions it ran and the hash of the toolchain’s lockfile. Publish that file with the release, so a consumer knows what to install before rebuilding.
{
"node": "v22.23.5",
"@voxgig/create-sdkgen": "0.31.9",
"@voxgig/sdkgen": "4.44.3",
"@voxgig/apidef": "8.32.4",
"typescript": "5.9.3",
"@hey-api/openapi-ts": "0.99.0",
"sdk package-lock.json sha256": "9ad5433fcffd85d5d3b1afe465fa5d3c35f95d2c3442a85c8236210b102abaf3"
}
Compare what each build would publish
Compare the file you publish, not the tree it came from. compare.mjs reads both tarballs entry
by entry, and exits 1 when their bytes differ.
node compare.mjs builds/a/bookshelf-sdk-0.0.1.npm.tar.gz builds/b/bookshelf-sdk-0.0.1.npm.tar.gz
builds/a/bookshelf-sdk-0.0.1.npm.tar.gz: 210 entries, sha256 e5a8391b2c6d839f5058ab5a82347b34713809d7908009fe1e8382468b0929b7
builds/b/bookshelf-sdk-0.0.1.npm.tar.gz: 210 entries, sha256 e5a8391b2c6d839f5058ab5a82347b34713809d7908009fe1e8382468b0929b7
same bytes: yes
A minute apart, the two tarballs are the same 210 entries and the same hash. sdkgen’s documentation says that generating again from the same model gives byte-stable output, and this run bears it out for the packaged artifact as well as the tree.
A Go module has no tarball to compare. Consumers check it against the h1 hash in go.sum, which
dirhash computes from filenames and
contents only, so no mtime or owner goes in. manifests.mjs computes it from each build’s
manifest and checks it against the hash Go’s own package wrote.
node manifests.mjs
heyapi.sha256 build a 16 files, build b 16, identical 16, in one only 0
go.sha256 build a 82 files, build b 82, identical 82, in one only 0
go module, build a: h1:hEJScSR0hl95/qOl8neHqoWnL+hGZ5RwepxaXu6aSx8=, the same as Go's dirhash wrote: yes
go module, build b: h1:hEJScSR0hl95/qOl8neHqoWnL+hGZ5RwepxaXu6aSx8=, the same as Go's dirhash wrote: yes
Find what varied when the hashes differ
The generator is rarely the cause. The 16 files of the Hey API client, with a package.json
beside them and checked out twice an hour apart, give three different results depending on how
they are packed.
node pack.mjs
the same Hey API client, checked out twice an hour apart, packed three ways
tar -czf, as it comes differ: mtime in 20 entries
tar normalized, then gzip -n same bytes
npm pack same bytes
Plain tar writes each file’s mtime into its header, and diffoscope, run once by record.sh,
shows exactly that:
--- client-1.tar.gz
+++ client-2.tar.gz
│ --- client-1.tar
├── +++ client-2.tar
│ ├── file list
│ │ @@ -1,19 +1,19 @@
│ │ -drwxr-xr-x 0 root (0) root (0) 0 2026-11-21 10:00:00.000000 client/
The fix is the one the Reproducible Builds archive guide
gives: sort the entries, set one mtime from
SOURCE_DATE_EPOCH, drop the owner,
and tell gzip not to store a name or time.
const tarball = execFileSync('tar', [
'--sort=name',
`--mtime=@${SOURCE_DATE_EPOCH}`,
'--owner=0',
'--group=0',
'--numeric-owner',
'--format=gnu',
npm pack needed no fix. npm 10.9.9 dated every entry 1985-10-26 and wrote owner 0, whatever
the files carried.1
Run the same check on Fern and Hey API
Hey API ran here, twice, and its 16 files matched. Its
get started page asks you to pin an
exact version, because the package is in initial development. Its
output options empty the output
folder on every run, and postProcess runs tools such as prettier or biome over it afterwards.
Those commands run whatever version your environment provides, so pin them in the same lockfile.
Fern was not run. Its fern generate reference
generates on Fern’s cloud after a login, on a guest session, or with --local in Docker or
Podman. In the sdk-config.yml format, targets run the newest generator unless you pin one. The
reference calls targets[].generatorVersion “the exact generator version used for this target”
in its entry. The
project structure page
says that pinning the CLI version in fern.config.json provides deterministic builds. Fern’s
self-hosted versioning page
shows each generated SDK recording cliVersion, generatorVersion, and originGitCommit in
.fern/metadata.json, the inputs file this page writes by hand. The
self-hosted page marks
--local generation as an Enterprise feature.
Check it worked
The suite checks the two committed builds, packs the client three ways, and tests that the comparison catches what it should.
test('the comparison names a one-byte change in one entry', (t) => {
const dir = scratch(t)
for (const n of [1, 2]) {
mkdirSync(join(dir, `b${n}`, 'client'), { recursive: true })
writeFileSync(join(dir, `b${n}`, 'client', 'a.ts'), 'export const a = 1\n')
writeFileSync(join(dir, `b${n}`, 'client', 'b.ts'), `export const b = ${n}\n`)
STEPS['tar normalized, then gzip -n'](join(dir, `b${n}`, 'client'), join(dir, `out${n}.tar.gz`))
}
const d = diffTarballs(readTarball(join(dir, 'out1.tar.gz')), readTarball(join(dir, 'out2.tar.gz')))
assert.equal(d.same, false)
assert.deepEqual(d.differ, { sha256: 1 })
})
node --test repro.test.mjs | tail -8
# tests 9
# suites 0
# pass 9
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 1316.255845
When it goes wrong
The hashes differ even though every file’s content matches. The archive carries modification times, an owner, or
directory order. Run compare.mjs, or diffoscope, to name the field, then fix the packaging
step, not the generator.
A rebuild months later differs where a rebuild the next minute did not. The generated
ts/package.json asks for typescript ^5.9.3, and the generator writes no lockfile for it.
Commit the package-lock.json the first npm install writes, and build with npm ci.
The release is signed, but a rebuild still differs. A signature or a provenance statement says who built the file and from which commit. It does not say that the file is what the commit builds, which is the question the two-build check answers.2
When not to do this
Do not stop at two runs on one machine. They share a kernel, a filesystem, and a host name, so a difference in any of the three cannot show. Put the second build on another runner image before you promise consumers a match.
Reproducibility alone is no reason to move to sdkgen. Hey API passed the same check on its TypeScript
client with one pin, and it is the smaller adoption for a TypeScript-only SDK. Fern records its
inputs in .fern/metadata.json without a script of yours, which suits a team that already
generates on Fern’s cloud.
Do not carry this result over to an SDK a coding agent writes. The two builds here are two runs of fixed generators, and this page measured no agent run. Run the same comparison on two agent runs from one prompt before you publish either.
Related how-tos
Last verified
Verified 2026-11-21 against Node 22.23.5, npm 10.9.9, @voxgig/create-sdkgen 0.31.9,
@voxgig/sdkgen 4.44.3, @hey-api/openapi-ts 0.99.0, golang.org/x/mod v0.30.0, GNU tar 1.35,
and Go 1.24.7. Every output block is what the command preceding it printed. Both builds ran in
one sandbox, one minute apart. diffoscope 339 ran once, inside record.sh, so the commands on
the page do without it. Fern’s part comes from its sdk-config.yml reference, its fern generate
reference, and its project structure and self-hosting pages, read but not run.
Footnotes
-
The date is set in
pacote, the library npm packs with. Its source gives every entry 1985-10-26T08:15:00Z. The comment beside it asks for a date in the 1980s because zip “is confounded by files dated at the Unix epoch 0” otherwise. The same options forcegziplevel 9, which, the comment says, seems to avoid some platform-specific optimizations that cause integrity mismatch errors. ↩︎ Back to text -
npm’s provenance page says a provenance statement lets you publicly establish where a package was built and who published it. Both are facts about the publishing run, while a consumer who rebuilds is asking about the bytes. ↩︎ Back to text