How-to › Release and secure packages

How to block a release when generated SDK files have drifted#

Regenerate every target in the release job, fail on drift inside the generated folders, name each file, and point the author at its template or component.

Audience
Platform team
Level
advanced
Topic
Version, changelog and automate releases
Languages
TypeScript, Python and Go
Verified

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
Kiota update with —clean-outputA Kiota client committed with its kiota-lock.jsonA plain update skips generation when nothing changed, so the flag is mandatoryYou want the gate to say which input to edit
orval —outdatedAn orval client, checked with no regeneration and no gitStray files are reported only when the config sets cleanYour generator is not orval
Regenerate then git diff —exit-codeAny generator, with no tool beyond gitA stray file passes unless the folders are deleted first, and nothing says where the fix goesYou need the gate to tell a fork from an extra
sdkgen check-drift with a scoped gateAn sdkgen project whose .sdk/ is edited on purposeTwo scripts to keep, and a full regeneration on every releaseOne generator, one target, and git diff is enough
Speakeasy generation action in PR modeSpeakeasy generates the SDK, and a person reviews each runDrift shows in a pull request to review, not as a failed checkYou 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.

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

  1. The scaffold’s own check-drift.sh explains 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

  2. orval’s CLI reference defines three statuses, outdated, missing and obsolete, and says obsolete is reported only when clean is configured. A file the generator would delete counts as drift only if the generator is allowed to delete it. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.