Regenerate SDKs in CI
Write a GitHub Actions or GitLab CI workflow that regenerates your SDKs on every push and opens a pull request or merge request with the changes.
orbitdocs sdk --workflow writes a CI workflow for you. On every push to your main branch, it extracts the spec, regenerates the SDKs and opens a pull request (GitHub) or merge request (GitLab) on the orbitdocs/sdks branch. You review the API changes and merge. Releases and changelogs stay in your hands.
GitHub Actions
Write the workflow
npx orbitdocs sdk --workflow githubThis writes .github/workflows/orbitdocs-sdks.yml at the root of your git repository. Running it again overwrites the file.
Let Actions open pull requests
In your repository, go to Settings → Actions → General → Workflow permissions. Turn on Allow GitHub Actions to create and approve pull requests.
Commit and push
The next push to main runs it. You can also start it by hand from the Actions tab.
What the workflow does, for a docs app in docs/:
# Regenerates the SDKs when the API changes and opens a pull request (OrbitDocs).
name: SDKs
on:
push:
branches: [main]
workflow_dispatch:
permissions:
contents: write
pull-requests: write
jobs:
sdks:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- uses: actions/setup-java@v4 # only when a non-TypeScript SDK is configured
with:
distribution: temurin
java-version: 21
- run: npm ci
- name: Extract specs and regenerate SDKs
working-directory: docs
run: npx orbitdocs extract && npx orbitdocs sdk
- name: Open a pull request
uses: peter-evans/create-pull-request@v7
with:
branch: orbitdocs/sdks
title: Regenerate SDKs
commit-message: 'chore(sdk): regenerate from the latest API'
body: Generated by `orbitdocs sdk`. Review the API changes before merging.When nothing changed, no pull request is opened. When one is already open, it is updated.
GitLab CI
Write the job
npx orbitdocs sdk --workflow gitlabThis writes orbitdocs-sdks.gitlab-ci.yml at the root of your git repository.
Include it
include:
- local: orbitdocs-sdks.gitlab-ci.ymlAdd a push token
The job pushes a branch, which the default CI token can't do.
- Create a project access token with the
write_repositoryscope (Settings → Access tokens), with at least the Developer role. - Add it as a masked CI/CD variable named
SDK_PUSH_TOKEN(Settings → CI/CD → Variables).
The job runs on pushes to the default branch, in the node:22-bookworm image. It installs a Java runtime when a non-TypeScript SDK is configured, runs npm ci, then orbitdocs extract and orbitdocs sdk in the docs app. If the SDKs changed, it commits them to orbitdocs/sdks, force-pushes, and opens a merge request into the default branch with Git push options. If nothing changed, it prints "SDKs are up to date" and exits.
Before you rely on it
Adapt the generated file to your repository
The workflow is a starting point. Check these against your setup:
- Package manager: it runs
npm ci, which needs apackage-lock.json. With pnpm or Yarn, replace the install step. - Branch: the GitHub workflow triggers on
main. Change it if your default branch has another name. - Building the Nest app: extraction loads your compiled app. A fresh CI checkout has no
dist/, so setsource.nest.build(for examplenest build) in the config, or add a build step beforeorbitdocs extract. - Extraction environment: if your app needs environment variables at import time, set them in
source.nest.envor in the job.
- The workflow only regenerates SDKs. It doesn't build or deploy the docs.
- Pull requests opened with GitHub's default token don't trigger other workflows. Use a personal access token or a GitHub App token in
create-pull-requestif you need CI to run on them. - Generated code never overwrites your own: see Keep your own code.
Run the contract tests too
Add a step after orbitdocs sdk to check the regenerated TypeScript SDK against the spec:
- name: SDK contract tests
working-directory: docs
run: npx orbitdocs sdk testSee SDK contract tests.