How-to › Release and secure packages

How to regenerate an SDK in CI when the spec changes#

Lint the changed OpenAPI document, regenerate with a pinned generator, refuse a run that loses an operation, and open a pull request that names the spec commit.

Audience
API producer
Level
advanced
Topic
Version, changelog and automate releases
Languages
TypeScript, Python and Go
Verified

Read first: Choose a release automation tool for an SDK repository

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
Fern CLIFern already generates your SDKs and its cloud may run the generatorsA FERN_TOKEN secret, and the document leaves your runner unless you add DockerNothing may leave the runner
NSwagC# or TypeScript clients from a .NET buildA .NET runtime in the job, and two client languages onlyYou ship Python or Go
oapi-codegenA Go client regenerated by go generate, with the tool pinned in go.modGo only, and doc comments that move whenever the document gains a descriptionYou need more than one language
sdkgenOne job regenerates TypeScript, Python and Go from one modelA Node toolchain to pin, and an exit 0 on a cut document that your job must catchYour generator already refuses bad input
Speakeasy sdk-generation-actionYou want a ready workflow that opens the pull request and proposes the versionA Speakeasy API key, direct mode by default, and a CLI version of latest unless pinnedYou must review every change before it reaches main
SpectralEvery row: lint the document before any generator reads itOne more pinned tool, and warnings that pass until someone fixes them in bulkNever 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.

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

  1. Fern’s SDK commands reference says remote generation requires authentication, by login or FERN_TOKEN, and that --local needs no login when writing to the local file system. The same page says --guest generates on a temporary guest session and cannot be combined with FERN_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

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.