How Soxom works

This page traces what happens between “I pushed to my Config Repository” and “there’s a new tagged release of my SDK on npm”. If you’ve read the Core Concepts, this is the dynamic version of that picture.

The 30-second version

┌────────────────────────────┐
│   Config Repository        │   you own this
│   openapi.yaml             │   "git push origin main"
│   soxom.yaml               │           │
└────────────────────────────┘           │
              │                          ▼
              │             ┌────────────────────────┐
              │   webhook   │   Soxom backend        │
              └────────────▶│   runs the generator   │
                            │   for each SDK Target  │
                            └────────────────────────┘
                                        │
                                        ▼
       ┌──────────────────────────────────────────────────┐
       │  Staging Repository  (one per SDK Target)        │
       │                                                  │
       │  codegen/next  ──▶  extended/next  ──▶  next     │
       │     (raw)          (+ custom code)    (merged)   │
       │                                          │       │
       │                                          ▼       │
       │                            staging-release PR    │
       │                            (next  ──▶  main)     │
       └──────────────────────────────────────────────────┘
                                        │   merge
                                        ▼
       ┌──────────────────────────────────────────────────┐
       │  Production Repository                           │
       │                                                  │
       │            production-release PR                 │
       │            (merge → git tag → publish)           │
       └──────────────────────────────────────────────────┘

Step by step

1. You push to the Config Repository

Your Config Repository is a normal GitHub repo that holds openapi.yaml and soxom.yaml. You commit and push changes the way you would to any other repo — typically through a feature branch and a PR on main.

A push (or PR merge) to main is the trigger for the rest of the pipeline. Pushes to other branches still produce builds; they land on codegen/<branch> in each Staging Repository so you can preview generated changes before merging.

2. GitHub fires a webhook to Soxom

The Soxom GitHub App receives the push event. Soxom enqueues a Build for the affected Project — one generator run per enabled SDK Target.

3. Soxom runs the generator(s) server-side

For each SDK Target, Soxom:

• Reads the commit’s openapi.yaml and soxom.yaml.
• Selects the right generator version (Python, TypeScript, Java, or Go preview).
• Runs the generator inside Soxom’s infrastructure.
• Captures logs and any validation diagnostics into the Build record.

You watch progress and inspect logs on the Builds page in the dashboard. Nothing runs on your machine.

4. Generated code lands on codegen/next

For each SDK Target, Soxom commits the raw generator output onto a dedicated branch in that target’s Staging Repository:

• codegen/next for builds from the Config Repository’s main.
• codegen/<branch> for builds from any other Config Repository branch.

These branches are Soxom-owned — Soxom force-updates them on every build, so don’t commit to them by hand. They are pure generator output, untouched by any human code.

5. Custom code is merged in on extended/next

Some SDKs need code that the generator can’t produce: hand-written helpers, exception classes, integration tests, or examples. You maintain that code on a separate hand-edited branch (typically extended/main) of the Staging Repository.

Soxom merges the latest codegen/next into your extensions to produce extended/next. Conflicts surface on the Build page so you can resolve them.

6. Final merged state on next

The next branch is the final state of the SDK for the current Config Repository revision — generator output plus your custom code. CI tests in the Staging Repository run against next so you can catch regressions before any release.

7. Soxom opens a staging-release PR

Once next is updated, Soxom opens (or updates) a staging-release PR from next into main in the Staging Repository. The PR:

• Includes the diff between the last staging release and the new code.
• Computes the new version using your Conventional Commit history (feat:, fix:, BREAKING CHANGE:).
• Generates a changelog entry.

You review the PR like any other. When you merge it, the Staging Repository’s main branch advances to the new release.

8. Soxom opens a production-release PR

Merging the staging PR triggers Soxom to open a production-release PR in the Production Repository. It contains the just-released staging code and the version bump.

9. Merging publishes the SDK

When you merge the production-release PR, Soxom:

• Creates a git tag (e.g. v1.4.0) on the Production Repository.
• Optionally publishes the package to your chosen registry (npm, PyPI, Maven Central, …) if you’ve supplied publishing credentials on the SDK Target.

Your users npm install, pip install, or mvn dependency:get and pick up the new version.

Why the two-repo split

Note

The Staging / Production split lets you run pre-release CI, hold breaking changes in next while you finalize migration notes, and keep the published Production Repository linear and tag-clean — without ever needing to rebase release branches.

• Staging Repositories are where iteration happens — preview branches, generator churn, extended code, CI.
• Production Repositories stay clean: a linear main, one merge per release, one tag per merge.

Where to go next

• Config Repository workflow — branch model, commit conventions, and webhooks.
• Staging Repository workflow — branch layout and custom-code conventions in depth.
• Production Repository workflow — versioning, tagging, and publishing.
• soxom.yaml reference — every field that shapes a build.