# 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.

Source: https://voxgig.com/howto/block-a-release-when-generated-sdk-files-drift

- Audience: platform-team
- Level: advanced
- Languages: typescript, python, go
- Verified: 2026-11-21
- Published: 2026-11-21

## 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](https://learn.microsoft.com/en-us/openapi/kiota/using) | 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](https://orval.dev/docs/reference/cli/) | 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](https://git-scm.com/docs/git-diff) | 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](https://github.com/voxgig/sdkgen/blob/main/docs/reference/cli.md) | 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](https://www.speakeasy.com/docs/sdks/manage/github-setup) | 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](https://www.speakeasy.com/docs/sdks/customize/code/custom-code/custom-code)
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](https://github.com/voxgig/sdkgen/blob/main/docs/reference/cli.md) says, and the
generated folders are not among them. On the branch with three hand edits, it printed this:

```text title="recorded/doctor-all.txt"
[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:

```text title="recorded/check-drift-all.txt"
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.

```bash
node gate.mjs --targets go,py,ts --manifest recorded/sdk-files.txt recorded/status-all.txt; echo "exit $?"
```

```text output
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`:

```yaml title="release-gate.yml"
      - 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:

```text title="recorded/gate-template.txt"
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](https://learn.microsoft.com/en-us/openapi/kiota/using) 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:

```text title="recorded/kiota-run.txt"
$ 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:

```bash
npx orval --config ./orval/hotfixed.config.mjs --outdated; echo "exit $?"
```

```text output
🍻 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.

```bash
node --test gate.test.mjs
```

```text output
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

- [Find hand edits in a generated SDK before you regenerate](/howto/find-hand-edits-before-regenerating)

- [Keep generated files out of a coding agent's edits](/howto/keep-generated-files-out-of-agent-edits)

- [Fail a build when a generator customization becomes a fork](/howto/audit-generator-customisations-for-drift)

- [Generate your first SDK with sdkgen](/howto/first-sdk-with-sdkgen)

- [Decide if a regenerated SDK is a minor or major release](/howto/regenerated-sdk-minor-or-major-release)

## 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.

[^1]: The scaffold's own [`check-drift.sh`](https://github.com/voxgig/create-sdkgen/blob/main/project/standard/.sdk/admin/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.

[^2]: orval's [CLI reference](https://orval.dev/docs/reference/cli/) 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.