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

Source: https://voxgig.com/howto/regenerate-an-sdk-in-ci-on-spec-change

- Audience: api-producer
- Level: advanced
- Languages: typescript, python, go
- Verified: 2026-11-22
- Published: 2026-11-22

## 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](/howto/choose-a-release-automation-tool-for-an-sdk).

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [Fern CLI](https://buildwithfern.com/learn/cli-api-reference/cli-reference/sdk-commands) | 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](https://github.com/RicoSuter/NSwag/wiki/CommandLine) | 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](https://github.com/oapi-codegen/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](https://github.com/voxgig/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](https://www.speakeasy.com/docs/speakeasy-reference/generation/ci-cd-pipeline) | 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](https://github.com/stoplightio/spectral/blob/develop/docs/guides/2-cli.md) | 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](https://www.speakeasy.com/docs/sdks/manage/versioning) 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:

```bash title="regen-job.sh"
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`:

```text title="records/isbn/job.txt"
== 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`:

```markdown title="records/isbn/pr-body.md"
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:

```text title="records/cut/unguarded.txt"
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:

```bash
node regen-guard.mjs spec api-cut.json
```

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

```text title="records/dropped/job.txt"
== 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:

```bash
node churn.mjs
```

```text output
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](https://github.com/RicoSuter/NSwag/wiki/CommandLine) shows. On
`api-v2.json`, `openapi2tsclient` added the field in four places:

```ts title="generated/nswag/api-v2.ts"
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:

```text title="records/other-generators.txt"
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.

```bash
node --test regen.test.mjs
```

```text output
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](https://docs.github.com/en/actions/concepts/security/github_token) 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](https://docs.npmjs.com/cli/v10/commands/npm-ci/) 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

- [Choose a release automation tool for an SDK repository](/howto/choose-a-release-automation-tool-for-an-sdk)

- [Block a release when generated SDK files have drifted](/howto/block-a-release-when-generated-sdk-files-drift)

- [Preview a regeneration as a diff before writing files](/howto/preview-a-regeneration-as-a-diff)

- [Drive code generation from a script instead of the CLI](/howto/drive-code-generation-from-a-script)

- [Keep a CLI in sync with an API spec as it changes](/howto/keep-a-cli-in-sync-with-the-spec)

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

[^1]: Fern's [SDK commands reference](https://buildwithfern.com/learn/cli-api-reference/cli-reference/sdk-commands)
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.