Staging repository

The Staging Repository is where Soxom assembles the next version of an SDK. It holds raw generator output, merges it with any custom code you’ve written, and exposes the integrated result on a working branch. There is exactly one Staging Repository per SDK Target.

One per SDK Target

If your Project defines three Targets — TypeScript, Python, and Java — Soxom creates three Staging Repositories:

myorg/acme-sdk-typescript-staging
myorg/acme-sdk-python-staging
myorg/acme-sdk-java-staging

Soxom owns these repositories and pushes to them as Builds run. You have read access and can open PRs against the extended/* branches to add custom code.

Branch model

Each Staging Repository uses a layered branch model. The arrows show how Soxom moves changes through it:

Config repo push                Staging repo branches
─────────────────               ─────────────────────

main ──────────────▶  codegen/next ──┐
                                     ├──▶ extended/next ──▶ next ──▶ main
                      (your custom   │                                 │
                       code lives    │                                 │
                       on extended/*)│                                 ▼
                                     │                          (last released)
feature/foo ───────▶  codegen/feature/foo ──▶ extended/feature/foo

Branch	Written by	Contains
codegen/next	Soxom	Raw generator output from Config repo main
codegen/<branch>	Soxom	Raw generator output from a Config repo branch (preview)
extended/next	You (via PR)	Generator output plus any hand-written custom code
extended/<branch>	You (via PR)	Per-branch custom-code overlay
next	Soxom	Final integrated result — the working branch for the next release
main	Soxom	The last released code (matches the latest production tag)

Note

Never push directly to codegen/*, next, or main. Soxom owns those. Open PRs against extended/* if you want to add custom code.

What happens on a build

When you push to the Config Repository’s main branch, Soxom:

1. Runs the generator server-side using your openapi.yaml + soxom.yaml.
2. Force-pushes the result to codegen/next in each Target’s Staging Repository.
3. Merges codegen/next into extended/next, preserving custom code on top.
4. Fast-forwards next to the merge result.

If step 3 produces conflicts between regenerated code and your custom code, the Build is marked conflict in the dashboard’s Builds view and next is left at its previous tip until you resolve the conflict on extended/next.

Per-branch previews

Pushing to a Config repo branch (say feature/cursor-pagination) follows the same pipeline but on a parallel branch line:

codegen/feature/cursor-pagination ──▶ extended/feature/cursor-pagination

This lets you compare the resulting SDK against next before merging the spec change to main. The dashboard shows a diff between any two extended/* branches so reviewers can see the SDK impact of a spec PR.

Adding custom code

Custom code lets you hand-write additions that the generator can’t express — helper methods, retry interceptors, idiomatic wrappers. To add it:

1. Clone the Staging Repository.
2. Check out extended/next (or extended/<branch> for a preview).
3. Add your files. Anything outside the paths the generator owns is preserved across regenerations.
4. Open a PR against extended/next. Once merged, the next Build will integrate it into next.

Plan-based line-count limits apply — see Custom code for details.

Surfacing problems

The Soxom dashboard’s Builds view shows the state of every recent Build per Target: generator failures, merge conflicts on extended/next, and the resulting next commit. Resolve conflicts there or in your local clone of the Staging Repository.

Next steps

• Production repository — where releases get tagged
• Versioning & releases — how next becomes main
• Config repository — the upstream input