Someone hot-fixed a header in the generated Python SDK and committed it, and the release passed.
The next regeneration writes the file from its template again, so the fix disappears from the
following release with no failed check. voxgig-sdkgen doctor reports the project as matching
its scaffold, because it never reads the generated output.
What you get
You will end up with a release job that regenerates every target, fails when a generated file differs, names it, and says where the change belongs. This is for you if a team commits generated SDKs and someone edits them by hand.
Short answer
Regenerate every target from nothing in the release job and compare with git. In an sdkgen
project, run the scaffold’s check-drift script, then fail on what git status reports inside
the target folders and name the template or component each file comes from. doctor alone exits
0 on a hand edit to generated output. Kiota needs --clean-output on update, and orval has its
own --outdated check.
You will need
Node 22 or later, git, a CI service that can run a job before publishing, and a generated SDK
committed to the repository. Verified 2026-11-21 against Node 22.23.5. The project here has ts,
py and go targets made from the Bookshelf document, committed, then changed on five branches,
one per scenario. Making the generator write the same bytes twice is a different task, covered
under reproducible builds.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| Kiota update with —clean-output | A Kiota client committed with its kiota-lock.json | A plain update skips generation when nothing changed, so the flag is mandatory | You want the gate to say which input to edit |
| orval —outdated | An orval client, checked with no regeneration and no git | Stray files are reported only when the config sets clean | Your generator is not orval |
| Regenerate then git diff —exit-code | Any generator, with no tool beyond git | A stray file passes unless the folders are deleted first, and nothing says where the fix goes | You need the gate to tell a fork from an extra |
| sdkgen check-drift with a scoped gate | An sdkgen project whose .sdk/ is edited on purpose | Two scripts to keep, and a full regeneration on every release | One generator, one target, and git diff is enough |
| Speakeasy generation action in PR mode | Speakeasy generates the SDK, and a person reviews each run | Drift shows in a pull request to review, not as a failed check | You need a hard stop before publish |
Voxgig maintains sdkgen; it is one row of five here, and the table does not rank them.
The three generic rows fail on any difference and leave the diagnosis to the author. The sdkgen
row costs a second script, and in return it reads the project’s own .sdk/ to say which file to
edit. Speakeasy trades the hard stop for a review, and with persistentEdits on, its
custom code page
says a hand edit is kept by a three-way merge rather than reverted.
Ask doctor, then regenerate from nothing
doctor compares the copies under .sdk/ with what target add would write, as its
CLI reference says, and the
generated folders are not among them. On the branch with three hand edits, it printed this:
[18:46:09.689] INFO: sdkgen doctor-end .sdk matches the scaffold (0 additive, 0 customized)
doctor exit 0
The scaffold’s check-drift script deletes every target folder, regenerates, and prints
git status. On the same branch it exited 1, naming all three:
check-drift: DRIFT. These differ from what the generator produces:
M py/bookshelf_sdk/entity/book_entity.py
M py/bookshelf_sdk/utility/prepare_headers.py
D ts/src/extra/isbn.ts
D output the generator no longer emits - delete it.
M output that changed - commit it.
?? output not committed - commit it.
Its legend assumes the generator is right, and tells the author M output that changed - commit it.
For a hot fix, committing the regenerated M file reverts the fix, which is the loss the gate
exists to prevent. Both commands behaved the same with sdkgen 4.45.0 installed.
Gate the release on the target folders
gate.mjs reads that status, fails on anything inside a target folder, and looks up the lever in
the project’s .sdk/. A file whose folder and name match a template came from that template;
anything else came from a component or the model. A line outside the targets is printed and
passes, so edits to .sdk/tm/, .sdk/src/cmp/ and project.aontu never trip it.
node gate.mjs --targets go,py,ts --manifest recorded/sdk-files.txt recorded/status-all.txt; echo "exit $?"
release gate: FAIL. 3 generated file(s) drifted:
M py/bookshelf_sdk/entity/book_entity.py
differs from what the generator writes; put the change in a component in .sdk/src/cmp/py/, or the model in .sdk/model/
M py/bookshelf_sdk/utility/prepare_headers.py
differs from what the generator writes; put the change in template .sdk/tm/py/pkg/utility/prepare_headers.py
D ts/src/extra/isbn.ts
committed, but the generator does not write it; put the change in a template under .sdk/tm/ts/ if it must ship, or delete it
exit 1
In CI, release-gate.sh runs check-drift and pipes git status into the gate, reading the
targets from .sdk/model/sdk.json. It stops with exit 2 when check-drift could not run, or
printed neither its clean line nor its drift line, so a failed generation never passes. The workflow runs it on a version tag, after npm ci in .sdk,
and the publish job lists it in needs:
- run: npm ci
working-directory: .sdk
- run: bash scripts/release-gate.sh
publish:
needs: generated-files-match
The full regeneration took about four seconds for three targets here.1
Move the hot fix where it survives
The fix belongs in the template the gate named. Made in .sdk/tm/py/pkg/utility/prepare_headers.py
and regenerated, the same change reaches the Python output, and the gate passes:
release-gate.sh, run on the branch with the template commit, sdkgen 4.44.3
release gate: pass. go, py, ts match what the generator writes.
exit 0
doctor then reports that template as CUSTOMIZED and still exits 0, because a later
target add merges toolchain updates into an edited copy.
Check drift with Kiota and orval
Kiota records the description’s hash in kiota-lock.json and, as its
using page says, skips generation when
the description and the parameters are unchanged and --clean-output is false. A plain update
left the hand edit in place; kiota-gate.sh, which adds the flag, caught both changes:
$ kiota update -o client; git status --porcelain -- client
Update of 1 clients completed successfully
(nothing listed)
$ bash kiota-gate.sh
kiota gate: FAIL. These differ from what Kiota writes:
M client/books/index.ts
D client/isbn.ts
exit 1
orval compares without writing anything. Its --outdated flag lists each file that differs and
exits 1, with no git and no regenerated tree:
npx orval --config ./orval/hotfixed.config.mjs --outdated; echo "exit $?"
🍻 orval v8.48.0 - A swagger client generator for typescript
bookshelf - 🔍 Bookshelf - Compared with the existing generated files
🛑 outdated: orval/hotfixed/model/book.ts
🛑 obsolete: orval/hotfixed/model/isbn.ts
🛑 Process exited with 2 outdated generated file(s) due to --outdated flag
exit 1
With clean: false in the same config, it reported book.ts alone.2
Check it worked
Thirteen tests cover the recorded runs, the gate and release-gate.sh. doctor passes every hand edit,
check-drift fails each, and a plain generate misses the stray file. The gate names each lever,
passes a .sdk/ line, and unquotes paths. release-gate.sh runs against stand-in projects, and
the orval test runs orval with each config.
node --test gate.test.mjs
1..13
# tests 13
# suites 0
# pass 13
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 1848.03145
When it goes wrong
A stray file ships although the gate ran. The job ran a plain npm run generate before
git status, which rewrote the two edited files but left ts/src/extra/isbn.ts in place, as
recorded/status-all-plain-generate.txt shows. Run check-drift, which deletes the target
folders first.
check-drift exits 2 in CI. It refuses a tree with uncommitted changes, and an earlier step
wrote a file. Run the gate in a job of its own, straight after checkout and npm ci.
The gate fails on a file someone meant to add. A file nobody generates is drift by design. Ship it
from a template under .sdk/tm/<target>/, so the generator writes it on every run.
When not to do this
Do not gate on doctor alone. It checks the copies in .sdk/ and passed all three hand edits
here.
Do not add this gate to an sdkgen project with one target. A regenerate and git diff --exit-code names the
same files, and the template path is a short lookup. Kiota is the better fit when the description lives
outside the repository, because its lock file records the parameters and the description’s
hash, so kiota update regenerates from it alone. orval suits a TypeScript-only team that wants a check with no regeneration
and no git.
Do not leave the scaffold’s legend in front of an author. “Commit it” is the wrong instruction for a hot fix, and the gate’s lever is the right one.
Related how-tos
Last verified
Verified 2026-11-21 against Node 22.23.5, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3 and
4.45.0, @voxgig/apidef 8.32.4, Kiota 1.39.0 and orval 8.48.0. Every output block is what the
command preceding it printed. The sdkgen and Kiota runs are recorded under recorded/ by
generate.sh, and the gate and the orval check are re-run. The workflow file was not run; its
actions and tools were checked against the Ubuntu 24.04 runner image’s list. Speakeasy was not
run, and its pull request mode is described from its documentation.
Footnotes
-
The scaffold’s own
check-drift.shexplains in its header why it is not wired into CI: it regenerates every target, which it calls minutes of work, too heavy for a per-push job. A release tag arrives far less often than a push, which is the schedule this page gives it. ↩︎ Back to text -
orval’s CLI reference defines three statuses, outdated, missing and obsolete, and says obsolete is reported only when
cleanis configured. A file the generator would delete counts as drift only if the generator is allowed to delete it. ↩︎ Back to text