Skip to content
Soxom

Config repository

The Config Repository is the single source of truth for what your SDK should look like. You own it, it lives in your GitHub organization, and every push to it tells Soxom to (re)generate your SDKs.

What it contains

Section titled “What it contains”

A Config Repository is a normal Git repository with two required files at the root:

.
├── openapi.yaml   # Your API definition (OpenAPI 3.0 or 3.1)
└── soxom.yaml     # SDK configuration (targets, resources, features)

You can add anything else you want — READMEs, build scripts, CI workflows — Soxom ignores everything except those two files.

Who owns it

Section titled “Who owns it”

You do. The Config Repository sits in your GitHub organization. Soxom creates it for you when you create a Project, but you have full write access from day one. Clone, edit, branch, and push like any other repo:

Terminal window
git clone git@github.com:myorg/acme-api-config.git
cd acme-api-config
$EDITOR openapi.yaml
git commit -am "feat: add pagination to /users"
git push

Soxom receives a webhook on every push and kicks off a Build for each affected SDK Target.

How branches map to builds

Section titled “How branches map to builds”

Every branch in the Config Repository corresponds to a build line in each Staging Repository:

Config repo branchTriggers build forStaging branch written
mainThe main release linecodegen/next
feature/fooA per-branch previewcodegen/feature/foo

This means you can experiment with breaking changes to your spec on a branch and see the resulting SDK in a parallel codegen/<branch> before merging anything. Open a PR in the Config Repository to invite review of the spec change; the Soxom dashboard will surface the corresponding SDK diff for each Target.

File requirements

Section titled “File requirements”

Soxom validates both files on every push and fails the Build early if they don’t pass:

  • openapi.yaml must be valid OpenAPI 3.0 or 3.1. References ($ref) to other files in the repo are supported.
  • soxom.yaml must declare at least:
    • version — configuration file version (currently "1.0")
    • sdk — package metadata (name, version, description)
    • spec — pointer to your OpenAPI file
    • targets — one or more SDK Targets to generate

See soxom.yaml reference for the full schema.

Conventional commits

Section titled “Conventional commits”

Soxom reads your Config Repository commit history to compute the next semver bump on each release. Use conventional commits (feat:, fix:, BREAKING CHANGE:) so the version stays predictable.

Next steps

Section titled “Next steps”