# How to vendor a generated SDK into your repo and take upgrades

> Vendor an SDK Catalog TypeScript SDK with `git subtree` or a patch series, keep two local patches across one regeneration, or wrap the Go module.

Source: https://voxgig.com/howto/vendor-a-generated-sdk-and-upgrade-it

- Audience: api-consumer
- Level: advanced
- Verified: 2026-11-22
- Published: 2026-11-22

## Short answer

Vendor the generated SDK with git subtree add --squash, commit each local change as its own patch, and pull a regeneration with git subtree pull --squash, or keep the patches as a series and reapply them with git am --3way. Resolve each conflict by taking the regenerated file and making the edit again. Where the SDK takes the change as an option, pass it instead and skip the patch.

---
## You will need

git with `git subtree`, which ships with git on Ubuntu, and Node 22 or later. The upstream is the
TypeScript SDK in [`voxgig-sdk/jsonplaceholder-sdk`](https://github.com/voxgig-sdk/jsonplaceholder-sdk),
whose README calls it unofficial and "not affiliated with" the API it wraps. The sample's
`upstream.bundle` holds its compiled files at two regenerations, so every command runs offline.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [git format-patch and git am patch series](https://git-scm.com/docs/git-am) | You want the vendored tree to stay exactly upstream plus a list of named changes | Each upgrade replays every patch, and a regenerated file stops `git am` on it | Your patches are few and history in one place suits you |
| [`git subtree`](https://github.com/git/git/blob/master/contrib/subtree/git-subtree.adoc) | You want the upstream inside your repository with no extra tooling for clones | Every pull is a merge you resolve, and the `--squash` choice must never change | You can take the change as an option and vendor nothing |
| [Kiota](https://learn.microsoft.com/en-us/openapi/kiota/middleware) | You generate the client yourself and add behavior through middleware | Its client is yours to regenerate and commit, with its runtime packages to keep current | You consume someone else's SDK as it ships |
| [oapi-codegen](https://github.com/oapi-codegen/oapi-codegen) | A Go client you generate, with headers set by a `RequestEditorFn` | One generated file per run, regenerated by you, and its runtime raised `go.mod` to Go 1.26 | The SDK comes from another team's repository |
| [SDK Catalog repo as upstream](https://github.com/voxgig-sdk/jsonplaceholder-sdk) | An SDK for a public API that its provider does not publish | Regenerations land as untagged commits, and nobody upstream answers for a bug | The API's provider publishes a supported SDK |
| [wrapper around the published package](https://pkg.go.dev/github.com/voxgig-sdk/jsonplaceholder-sdk/go) | The package is published and takes your change as an option | A bug stays unfixed until upstream ships, and only Go is published here | You must change behavior that no option reaches |

Voxgig maintains the SDK Catalog and the generator behind it. It is one of six options here,
not the recommendation.

A vendored copy buys offline builds and full control, and each regeneration then becomes your
merge.
Wrapping keeps an upgrade to a version bump, at the price of waiting on upstream for a fix.
Kiota and oapi-codegen sit on the other side: a team that generates its own client never vendors
it, and puts its additions in code the generator never writes.

## Vendor the earlier regeneration and patch it

The catalog's regenerations land on `main` without a tag. The repository's newest TypeScript tag
predates both commits used here.

```bash
node records.mjs
```

```text output
the catalog repository
  main: a21ce5a97d8ed4c85e02123b61a67a3a408d60a9
  old:  317cc9dcf13787659643517b15d436d47cc8952e 2026-10-01 Regenerate on sdkgen 4.33.0 and apidef 8.22.1
  new:  a21ce5a97d8ed4c85e02123b61a67a3a408d60a9 2026-11-03 Regenerate on sdkgen 4.38.0 and apidef 8.27.0
  newest ts/ tag: ts/v0.0.7 2026-08-13
  commits to ts/ after that tag: 12
  npm view @voxgig-sdk/jsonplaceholder-sdk: exit 1
the published Go module, wrapped
  go.mod: github.com/voxgig-sdk/jsonplaceholder-sdk/go v0.0.8-0.20261001173714-317cc9dcf137 // indirect
  load post 1: title=Lamp keys=[body id title userId]
  stand-in saw: GET /posts/1 user-agent="shop-billing/1.0" x-request-source="shop-billing"
  go.mod: github.com/voxgig-sdk/jsonplaceholder-sdk/go v0.0.8-0.20261103055737-a21ce5a97d8e
  load post 1: title=Lamp keys=[body id title userId]
  stand-in saw: GET /posts/1 user-agent="shop-billing/1.0" x-request-source="shop-billing"
  go1.24.7
oapi-codegen
  oapi-codegen v2.8.2, 277 lines in client/posts.gen.go
  go.mod: go 1.26.0
  load post 1: status=200 title=Lamp
  stand-in saw: GET /posts/1 user-agent="shop-billing/1.0" x-request-source="shop-billing"
```

Pin a commit, not a tag. The TypeScript package, `@voxgig-sdk/jsonplaceholder-sdk` in its
`package.json`, is not on npm, so a TypeScript team has no package to wrap and vendors the source.

Add the upstream with `git subtree add --prefix=vendor/jsonplaceholder <upstream> regen-old
--squash`. Then apply the two local changes as patches. The first sets your User-Agent right
before the SDK calls `fetch`:

```diff title="patches/0001-Send-our-own-User-Agent-from-the-vendored-SDK.patch"
diff --git a/vendor/jsonplaceholder/dist/utility/FetcherUtility.js b/vendor/jsonplaceholder/dist/utility/FetcherUtility.js
index 57f5771..cf14ffd 100644
--- a/vendor/jsonplaceholder/dist/utility/FetcherUtility.js
+++ b/vendor/jsonplaceholder/dist/utility/FetcherUtility.js
@@ -14,6 +14,8 @@ async function fetcher(ctx, fullurl, fetchdef) {
             ' (URL was: "' + fullurl + '")');
     }
     const fetch = options.system.fetch;
+    // LOCAL PATCH: identify this service to the API.
+    fetchdef.headers = Object.assign({}, fetchdef.headers, { 'user-agent': 'shop-billing/1.0' });
     const response = await fetch(fullurl, fetchdef);
     return response;
 }
```

The second adds an `x-request-source` header in `PrepareHeadersUtility.js`. The patches are
compiled JavaScript, because the vendored tree is what Node loads.

## Pull one regeneration through each route

Pull the later regeneration both ways, resolve, and check what the vendored SDK sends.

```bash
node upgrade.mjs
```

```text output
git subtree, --squash on add and on pull
  pull: exit 1, conflicts in dist/utility/FetcherUtility.js, dist/utility/PrepareHeadersUtility.js
  load post 1: title=Lamp, test mode: ok
  stand-in saw: GET /posts/1 user-agent="shop-billing/1.0" x-request-source="shop-billing"
git subtree, --squash on add, none on pull
  pull: exit 128, fatal: refusing to merge unrelated histories
git subtree, no --squash on add, --squash on pull
  pull: exit 1, conflicts in dist/utility/FetcherUtility.js, dist/utility/PrepareHeadersUtility.js
patch series, git am --3way on the new regeneration
  git am on the old: exit 0; on the new: exit 128, conflicts in dist/utility/FetcherUtility.js, dist/utility/PrepareHeadersUtility.js; refreshed 2 patches
  load post 1: title=Lamp, test mode: ok
  stand-in saw: GET /posts/1 user-agent="shop-billing/1.0" x-request-source="shop-billing"
no patch, regen-old as released
  load post 1: title=Lamp, test mode: ok
  stand-in saw: GET /posts/1 user-agent=null x-request-source=null
no patch, regen-old, with the headers passed as an SDK option
  load post 1: title=Lamp, test mode: ok
  stand-in saw: GET /posts/1 user-agent="shop-billing/1.0" x-request-source="shop-billing"
no patch, regen-new as released
  load post 1: title=Lamp, test mode: ok
  stand-in saw: GET /posts/1 user-agent="Mozilla/5.0 (compatible; JsonplaceholderSDK/1.0)" x-request-source=null
no patch, regen-new, with the headers passed as an SDK option
  load post 1: title=Lamp, test mode: ok
  stand-in saw: GET /posts/1 user-agent="shop-billing/1.0" x-request-source="shop-billing"
```

Both routes stopped on the same two files. The regeneration rewrote the lines around each patch:
it added a guard and a default User-Agent between `const fetch` and the call, and cookie handling
before `return out`. Each conflict is resolved the same way, by taking the regenerated file and
making the edit again with `patch-edits.mjs`, which refuses a file that already holds the edit.

The series route then refreshes the patches with `git format-patch`, so the next upgrade starts
from patches written against this regeneration. Both routes end with the same tree.

The last four runs carry the finding that matters most. Upstream's `headers` option sends both
headers on both regenerations with no patch at all. It does not carry every header: an
`authorization` header passed the same way never reached the stand-in, which the test also
asserts. Read the SDK's options before you patch it.

## Check it worked

The test rebuilds each route in a scratch repository. It asserts the conflicts, the headers the
stand-in received, and the offline test mode. It also checks that the resolved tree differs from
the regeneration in the two patched files only.

```bash
node --test vendor.test.mjs
```

```text output
1..8
# tests 8
# suites 0
# pass 8
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 3375.500747
```

The catalog's own test suite is TypeScript and rebuilds `dist/` from `src/` before it runs, which
would overwrite a patch made to the compiled files. The sample therefore checks the vendored build
with its own test and the SDK's offline test mode.

## Add the same headers with oapi-codegen and Kiota

A team on oapi-codegen generates its own Go client and commits the one file it writes. The
headers go in a `RequestEditorFn` in the team's code, so a regeneration rewrites the file without
touching them. `record.sh` ran it once against the stand-in, as the catalog record earlier shows.

```go title="go-oapi/main.go"
func shopHeaders(_ context.Context, req *http.Request) error {
	req.Header.Set("User-Agent", "shop-billing/1.0")
	req.Header.Set("X-Request-Source", "shop-billing")
	return nil
}
```

Kiota puts the same change in a middleware handler that you register when you build the HTTP
client, as its [middleware page](https://learn.microsoft.com/en-us/openapi/kiota/middleware)
shows for TypeScript, C#, and Python. That page lists a default User Agent handler that adds the
Kiota HTTP library version to the header. Kiota was not run here, so this paragraph rests on that
page alone.

The Go wrapper takes the same route through the catalog SDK's own options, and its upgrade was
one `go get` of a pseudo-version.

```go title="go-wrap/main.go"
// NewShopClient is the whole wrapper.
func NewShopClient(base string) *sdk.JsonplaceholderSDK {
	return sdk.NewJsonplaceholderSDK(map[string]any{
		"base": base,
		"headers": map[string]any{
			"user-agent":       "shop-billing/1.0",
			"x-request-source": "shop-billing",
		},
	})
}
```

## When it goes wrong

`git subtree pull` fails with `refusing to merge unrelated histories`. The add used `--squash`
and the pull did not, so git sees two histories with no common commit. Pull with the same
`--squash` choice the add used, every time.[^1]

`git am --3way` stops on a patch. The regeneration changed the lines around it. Take the
regenerated file with `git checkout --ours`, make the edit again, `git add` it, and run
`git am --continue`. In a `git subtree` merge, the regenerated side is `--theirs`.

The User-Agent changes after an upgrade without a conflict. The regeneration added a default
agent, so an SDK you never patched starts sending `Mozilla/5.0 (compatible; JsonplaceholderSDK/1.0)`.

## When not to do this

Do not vendor to change a setting the SDK already takes. The catalog SDK's `headers` option did
the work of both patches on both regenerations.

Do not vendor a catalog SDK expecting upstream to fix a bug for you. The README disclaims
affiliation with the API, and the repository regenerates on its own schedule. A vendored copy
makes that schedule your merge queue.

Choose oapi-codegen when you can generate the Go client yourself from the provider's document:
its editors keep your headers out of the generated file. Choose Kiota for the same reason in C#,
TypeScript or Python, the languages its middleware page shows, with middleware in place of
editors. Wrap the published Go module when you can, since its upgrade is a version bump.

This page vendored no SDK that the API's own provider publishes and supports, such as one its
provider generates with Speakeasy or Fern, so it holds no record of that case. There, a bug report
goes to the team that ships the SDK, which makes wrapping its package the first route to try.

## Related how-tos

- [Regenerate an SDK with a three-way merge and keep edits](/howto/regenerate-sdk-with-three-way-merge)

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

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

- [Install an SDK Catalog package for a public API](/howto/install-a-catalog-sdk-for-a-public-api)

## Last verified

Verified 2026-11-22 against Node 22.23.5 and git 2.43.0, on the catalog commits `317cc9d` and
`a21ce5a`. The Go wrapper and oapi-codegen v2.8.2 ran once, in `record.sh`, against a stand-in,
and their output is committed. Kiota was read from its documentation and not run.

[^1]: The
[git-subtree documentation](https://github.com/git/git/blob/master/contrib/subtree/git-subtree.adoc)
says `--squash` makes "a single commit that contains all the differences you want to merge".
With it, the page adds, you can "switch back and forth between different versions" rather than
only move forward. It says nothing about a pull that drops the flag. In the sample, a pull without it after
a squashed add stopped with `refusing to merge unrelated histories`, and the reverse pairing
reached the same two content conflicts as a matched pull.