A merge leaves api.json cut off after "paths": . Your regeneration job runs npm run generate,
which exits 0, and opens a pull request that takes Book out of the TypeScript client. The same
diff rewrites 31 files and deletes 3, so it reads to a reviewer like routine churn.
What you get
You will end up with a job that regenerates every target when the document changes and opens a pull request naming the spec commit. It refuses a document or a run that would delete code. This is for you if you publish SDKs generated from a document under git.
Short answer
Trigger a job on a change to the OpenAPI document. Lint it with Spectral and fail on errors, check
that it parses and declares operations, then regenerate with the generator version a lockfile pins.
Before opening a pull request, check that no operation left the model and every changed file is
one the generator writes. For sdkgen, run npm ci and npm run generate in .sdk, because its
exit status alone passes a cut-off document.
You will need
Node 22 or later, an OpenAPI 3 document under git, and an sdkgen project with its
.sdk/package-lock.json committed, which is what pins the generator. A CI runner that may push
branches and open pull requests. The sample runs offline against records of the job’s runs,
listed in its README.md. Picking the tool that tags and publishes afterwards is
a separate decision.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| Fern CLI | Fern already generates your SDKs and its cloud may run the generators | A FERN_TOKEN secret, and the document leaves your runner unless you add Docker | Nothing may leave the runner |
| NSwag | C# or TypeScript clients from a .NET build | A .NET runtime in the job, and two client languages only | You ship Python or Go |
| oapi-codegen | A Go client regenerated by go generate, with the tool pinned in go.mod | Go only, and doc comments that move whenever the document gains a description | You need more than one language |
| sdkgen | One job regenerates TypeScript, Python and Go from one model | A Node toolchain to pin, and an exit 0 on a cut document that your job must catch | Your generator already refuses bad input |
| Speakeasy sdk-generation-action | You want a ready workflow that opens the pull request and proposes the version | A Speakeasy API key, direct mode by default, and a CLI version of latest unless pinned | You must review every change before it reaches main |
| Spectral | Every row: lint the document before any generator reads it | One more pinned tool, and warnings that pass until someone fixes them in bulk | Never skip it; tune the ruleset instead |
Voxgig maintains sdkgen. It is one of the six rows here, and the lint row goes with whichever generator you pick.
The hosted rows do the most for you: Speakeasy proposes the version bump and Fern runs the
generators, and each needs a vendor token in CI. A self-run generator is one more tool to pin,
but the document never leaves your runner. Speakeasy computes its bump from info.version and a document
checksum, as its versioning page says.
Run the job in a scratch repository
regen-job.sh is the job’s body. regen.yml runs it on a push to main that changes
.sdk/def/api.json, then commits to a regen/<commit> branch and opens the pull request with
gh pr create. These lines lint, check, regenerate, and check again:
echo "== lint $SPEC"
SCARF_ANALYTICS=false npx --yes "$SPECTRAL" lint "$SPEC" --ruleset .spectral.yaml --fail-severity error
echo "== check the document's structure"
node scripts/regen-guard.mjs spec "$SPEC"
echo "== regenerate"
before="$(mktemp)"
git show HEAD:.sdk/model/sdk.json > "$before"
(cd .sdk && npm ci --no-audit --no-fund > /dev/null && npm run generate > generate-output.log 2>&1)
echo "== check that no operation left the model"
node scripts/regen-guard.mjs kept "$before" .sdk/model/sdk.json ${ALLOW_REMOVED_OPERATIONS:+--allow-removed}
SCARF_ANALYTICS=false turns off the install analytics of @scarf/scarf, which Spectral 6.17.1
depends on. record.sh ran the job in a scratch repository after a commit that adds
isbn to Book:
== lint .sdk/def/api.json
✖ 12 problems (0 errors, 12 warnings, 0 infos, 0 hints)
== check the document's structure
spec ok: 5 operations
== regenerate
== check that no operation left the model
kept ok: 5 of 5 operations
== check the output
output ok: 5 operations in the model, 19 changed files, all generated
== pull request body written
regen-job.sh exit 0
The last check reads git status --porcelain=v1 -z --untracked-files=all, which lists each new
file on its own instead of its directory, and never quotes a path. It accepts a file only if
.sdk/log/generated.jsonl or docgen’s .sdk/doc/generated.json lists it, or it is one of the
model step’s own files. A hand
edit to .sdk/model/project.aontu or a workflow file stops the job. The pull request body comes
from pr-body.mjs:
Regenerated from `.sdk/def/api.json` at da34752cbe3b25d995fd4c7135f25dfda9b22b08 (info.version 1.1.0).
- document sha256: 7ce4fdd1e07a046b869bb59ff0c10295a160679dca3762542de8d6034938e9de
- generator: sdkgen 4.44.3, apidef 8.32.4
Refuse a document the generator accepts
record.sh committed api-cut.json and ran npm run generate alone, as a job that trusts the exit
status would:
npm run generate exit 0, 0 WARN or ERROR lines
ts/src/BookshelfSDK.ts lines naming Book: 18 before, 14 after
ts/src/entity/BookEntity.ts still on disk: yes
git status: 31 modified, 3 deleted
@voxgig/sdkgen 4.45.0 with @voxgig/apidef 8.33.1 gave the same exit and the same four
missing lines. The job stops earlier, at the lint step, because Spectral reports a parser error on
the cut file. The structure check stops it too, without relying on the ruleset:
node regen-guard.mjs spec api-cut.json
refused: the document is not JSON (Unexpected end of JSON input)
It also refuses "paths": null and a paths object with no operations, the shapes a cut takes
once a lenient parser has read it. A document that parses and has lost a path passes both checks,
so the job compares the model with the one the last generation committed:
== check that no operation left the model
refused: DELETE /books/{bookId} (book.remove) was in the model and is not now
refused: GET /books/{bookId} (book.load) was in the model and is not now
refused: PATCH /books/{bookId} (book.update) was in the model and is not now
regen-job.sh exit 1
Remove a path on purpose by running the job with ALLOW_REMOVED_OPERATIONS=yes.
Lint before you generate, and know what a warning costs
--fail-severity error passes warnings, so twelve operation-tags and operation-description
warnings reach the generators. Fixing them later is one commit whose diff lands in every
regenerated SDK. churn.mjs counts the lines each generator moved. For sdkgen it reads the scratch
repository’s git diff --numstat over source and tests in ts/, py/ and go/. For NSwag and
oapi-codegen it diffs the one client file each wrote:
node churn.mjs
change sdkgen code NSwag oapi-codegen
add isbn to Book +35 -5 +4 -0 +1 -0
fix the 12 lint warnings +0 -0 +0 -0 +56 -0
oapi-codegen writes each new description into a doc comment, so fixing the warnings moved 56
lines of its client. sdkgen and NSwag left their code alone. sdkgen rewrote six other files: the
root README.md, SUMMARY.md, two model files, and two of docgen’s QA files. Fix the warnings once, before you switch the job on, so the first automatic
pull request carries only the spec change.
Wire NSwag and oapi-codegen into the same job
NSwag runs from a configuration document with nswag run nswag.json, or one command per client,
as its command-line page shows. On
api-v2.json, openapi2tsclient added the field in four places:
export class Book implements IBook {
id?: string;
title?: string;
author?: string;
published?: number;
isbn?: string;
oapi-codegen’s README pins the tool with go get -tool and runs it from a //go:generate line,
so the job is go generate ./... and the same git status check. Both refused this cut document
with a nonzero exit:
nswag openapi2tsclient api-cut.json: exit 255, JsonSerializationException: Unexpected end when setting paths's value
oapi-codegen api-cut.json: exit 1, failed to load OpenAPI specification
Fern regenerates with fern generate --group <group>, which selects a group from the legacy
generators.yml; its current sdk-config.yml takes --target. Remote generation reads a
FERN_TOKEN from the job.1
Check it worked
The suite rebuilds the pull request body from the committed inputs and tests the workflow’s shape. It feeds the guard a hand-edited file, a workflow file, a dropped operation, a lost path, and one record instead of two. It also runs the job’s status command in a scratch repository that gained a new entity’s directories.
node --test regen.test.mjs
1..18
# tests 18
# suites 0
# pass 18
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 236.368299
When it goes wrong
The pull request opens, but its checks wait. A pull request opened with GITHUB_TOKEN starts
its pull_request runs in an approval-required state, as GitHub’s
token page says. Approve
them, or open the pull request with a GitHub App token.
The guard refuses a file the generator wrote. sdkgen’s record lists the targets and root files,
and docgen keeps its own, so a guard that reads one record refuses SUMMARY.md. Pass both
records, as regen-job.sh does.
The pull request mixes a generator upgrade into the spec change. A job that runs npm install
with a version, or without the lockfile, regenerates with whatever it resolved. npm ci installs
the lockfile and, as its documentation says,
exits with an error when the lockfile and package.json disagree. Bump the generator in its own
reviewed change.
When not to do this
Do not open a pull request per spec commit when the document changes several times a day. Run the job on a schedule instead, and let each run update one branch.
Keep sdkgen out of a job that trusts exit codes. NSwag and oapi-codegen both refused the
cut document on their own, and sdkgen 4.44.3 and 4.45.0 did not. oapi-codegen is the smaller job
when Go is the only client, because go generate and a git diff are the whole pipeline.
Do not let a hosted action commit to main. Speakeasy’s default mode is direct, so set mode: pr if a person must read the diff first.
Do not lint with --fail-severity warn on the first day. Fix the existing warnings first, then
tighten the threshold.
Related how-tos
Last verified
Verified 2026-11-22 against Node 22.23.5, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3,
@voxgig/apidef 8.32.4, Spectral 6.17.1, NSwag 14.8.0 on the ASP.NET Core runtime 10.0.15 and
oapi-codegen v2.8.2. Every output block is what the command preceding it printed, and each titled
record is a file record.sh wrote. NSwag ran once in record.sh and its clients are committed.
The workflow was not run on GitHub; its shape is tested. Fern and Speakeasy were not run, and
their commands and modes come from their CLI and workflow references.
Footnotes
-
Fern’s SDK commands reference says remote generation requires authentication, by login or
FERN_TOKEN, and that--localneeds no login when writing to the local file system. The same page says--guestgenerates on a temporary guest session and cannot be combined withFERN_TOKEN. That makes three ways for a CI job to run it: a token, a container runtime, or a guest session, which sends the document to Fern without an account. ↩︎ Back to text