This document describes the automated publishing workflows for Sim's SDK packages and CLI tools. It covers version detection, package registry publishing (npm and PyPI), and GitHub release creation. For information about using the SDKs to interact with deployed workflows, see the API documentation. For general CI/CD pipeline information including Docker image publishing, see CI/CD Pipeline.
Sim publishes three primary packages to public registries:
| Package | Registry | Package Name | Workflow File |
|---|---|---|---|
| TypeScript SDK | npm | simstudio-ts-sdk | .github/workflows/publish-ts-sdk.yml |
| Python SDK | PyPI | simstudio-sdk | .github/workflows/publish-python-sdk.yml |
| CLI | npm | simstudio | .github/workflows/publish-cli.yml |
All publishing workflows are triggered automatically when changes are pushed to the main branch in their respective package directories. Each workflow includes version checking to prevent duplicate publishes and creates GitHub releases with version-specific tags.
Sources: .github/workflows/publish-ts-sdk.yml1-98 .github/workflows/publish-python-sdk.yml1-92 .github/workflows/publish-cli.yml1-72
Publishing Flow Overview
This diagram illustrates the automated SDK publishing pipeline. Each package type (TypeScript, Python, CLI) follows a similar pattern: test, build, version check, conditional publish, and optional GitHub release creation.
Sources: .github/workflows/publish-ts-sdk.yml .github/workflows/publish-python-sdk.yml .github/workflows/publish-cli.yml
The TypeScript SDK publishing workflow triggers on pushes to main that modify files in the packages/ts-sdk/** directory:
.github/workflows/publish-ts-sdk.yml1-8
The workflow performs the following steps:
bun install --frozen-lockfile with Bun cachebun run test in the packages/ts-sdk directorybun run build to compile the SDK.github/workflows/publish-ts-sdk.yml19-50
Version extraction uses Node.js to read the package.json file:
.github/workflows/publish-ts-sdk.yml52-55
The workflow then checks if the version already exists on npm to prevent duplicate publishes:
.github/workflows/publish-ts-sdk.yml57-64
If the version doesn't exist, the workflow publishes to npm with public access:
.github/workflows/publish-ts-sdk.yml66-71
The NODE_AUTH_TOKEN secret authenticates with npm using a token stored in GitHub Secrets.
After successful npm publish, the workflow creates a GitHub release with:
typescript-sdk-vX.Y.ZTypeScript SDK vX.Y.Z.github/workflows/publish-ts-sdk.yml77-98
Sources: .github/workflows/publish-ts-sdk.yml
The Python SDK workflow uses Python 3.12 with pip caching:
.github/workflows/publish-python-sdk.yml19-28
Python SDK build uses standard Python tooling:
pip install build twine pytest requests tomlipytest tests/ -v with PYTHONPATH=.tomli to parse pyproject.tomlpython -m build creates wheel and source distributionstwine check dist/* validates the built package.github/workflows/publish-python-sdk.yml25-57
The workflow checks PyPI for existing versions using pip index versions:
.github/workflows/publish-python-sdk.yml40-47
Publishing uses Twine with token authentication:
.github/workflows/publish-python-sdk.yml59-65
The TWINE_USERNAME is set to __token__ (PyPI's standard token username) and TWINE_PASSWORD contains the API token from GitHub Secrets.
Similar to the TypeScript SDK, successful PyPI publishes trigger GitHub release creation with:
python-sdk-vX.Y.Zpip install simstudio-sdk==X.Y.Z.github/workflows/publish-python-sdk.yml71-92
Sources: .github/workflows/publish-python-sdk.yml
The CLI package workflow is simpler than the SDK workflows as it targets npm only and doesn't create GitHub releases:
.github/workflows/publish-cli.yml1-72
| Aspect | CLI Workflow | SDK Workflows |
|---|---|---|
| Test step | Not included | Tests run before build |
| Node version | 18 | 22 (TypeScript SDK) |
| GitHub Release | Not created | Created on publish |
| Package name | simstudio | simstudio-ts-sdk, simstudio-sdk |
The CLI workflow follows the same pattern: build → version check → conditional publish, but skips the GitHub release creation step.
Sources: .github/workflows/publish-cli.yml
Version Detection Flow
All publishing workflows implement idempotent publishes by checking if the target version already exists in the registry. This prevents workflow failures from duplicate version errors and allows safe re-runs.
Sources: .github/workflows/publish-ts-sdk.yml52-75 .github/workflows/publish-python-sdk.yml36-69 .github/workflows/publish-cli.yml49-71
For main application releases (not SDK-specific), the `scripts/create-single-release.ts` script generates comprehensive release notes. This script is called from the main CI workflow when a version commit is detected:
.github/workflows/ci.yml286-311
GitHub Release Generation
The release script categorizes commits by type (features, fixes, improvements, other), extracts PR numbers, identifies contributors, and generates a formatted markdown release body.
Sources: scripts/create-single-release.ts1-416
The script uses pattern matching to categorize commits:
| Category | Patterns | Example |
|---|---|---|
| Features | feat:, feat(, feat! | feat: Add new API endpoint |
| Bug Fixes | fix:, fix(, fix! | fix: Resolve memory leak |
| Improvements | improve:, perf:, refactor: | perf: Optimize query performance |
| Other | chore:, docs:, ci:, test: | chore: Update dependencies |
scripts/create-single-release.ts226-265
Generated release bodies include:
scripts/create-single-release.ts267-349
Sources: scripts/create-single-release.ts
Each SDK uses a distinct tag prefix to avoid conflicts:
| Package | Tag Format | Example |
|---|---|---|
| TypeScript SDK | typescript-sdk-vX.Y.Z | typescript-sdk-v0.2.5 |
| Python SDK | python-sdk-vX.Y.Z | python-sdk-v0.1.3 |
| Main Application | vX.Y.Z | v0.5.24 |
This allows independent versioning of SDKs and the main application. The main application version is detected from commit messages matching the pattern vX.Y.Z: Description.
Sources: .github/workflows/publish-ts-sdk.yml83 .github/workflows/publish-python-sdk.yml77 .github/workflows/ci.yml37
TypeScript SDK and CLI workflows use Bun's dependency cache:
.github/workflows/publish-ts-sdk.yml30-39
The Python SDK workflow uses pip caching:
.github/workflows/publish-python-sdk.yml23
These caching strategies significantly reduce workflow execution time by reusing downloaded dependencies across runs.
Sources: .github/workflows/publish-ts-sdk.yml30-39 .github/workflows/publish-python-sdk.yml20-23
| Secret | Purpose | Used By |
|---|---|---|
NPM_TOKEN | npm registry authentication | TypeScript SDK, CLI |
PYPI_API_TOKEN | PyPI authentication | Python SDK |
GITHUB_TOKEN | GitHub API access (automatic) | All workflows |
GH_PAT | GitHub Personal Access Token | Release creation script |
All publishing workflows require:
.github/workflows/publish-ts-sdk.yml9-10
The contents: write permission allows workflows to create GitHub releases and tags.
Sources: .github/workflows/publish-ts-sdk.yml9-10 .github/workflows/publish-python-sdk.yml9-10 scripts/create-single-release.ts6
The TypeScript SDK build process (referenced in packages/ts-sdk/package.json) produces:
The Python build creates:
.whl).tar.gz)The twine check command validates both distribution types before upload:
.github/workflows/publish-python-sdk.yml54-57
The CLI package bundles into a single executable script with proper shebang and permissions for command-line use.
Sources: .github/workflows/publish-ts-sdk.yml48-50 .github/workflows/publish-python-sdk.yml49-65 .github/workflows/publish-cli.yml45-47
If version checking fails (e.g., network issues), workflows default to attempting publish, which will fail explicitly if the version exists. This fail-safe approach prevents silent skips due to transient errors.
All workflows include test and build steps that must pass before publishing. Failed tests or builds prevent package publication.
Publishing failures are logged explicitly. Common causes include:
The CLI workflow demonstrates the skip logging pattern:
.github/workflows/publish-cli.yml70-72
Sources: .github/workflows/publish-ts-sdk.yml73-75 .github/workflows/publish-python-sdk.yml67-69 .github/workflows/publish-cli.yml70-72
The main CI workflow includes version detection for application releases:
This job extracts version from commit messages using regex: ^(v[0-9]+\.[0-9]+\.[0-9]+):. Only commits on the main branch matching this pattern trigger version-specific tagging.
The create-release job depends on multi-architecture manifest creation and only runs for detected version commits:
.github/workflows/ci.yml286-311
This ensures releases are created only after all Docker images are successfully built and pushed.
Sources: .github/workflows/ci.yml22-46 .github/workflows/ci.yml286-311
The SDK publishing system provides:
All publishing workflows follow the same pattern: test → build → version check → conditional publish → optional GitHub release, ensuring consistency across package types.
Sources: .github/workflows/publish-ts-sdk.yml .github/workflows/publish-python-sdk.yml .github/workflows/publish-cli.yml scripts/create-single-release.ts
Refresh this wiki
This wiki was recently refreshed. Please wait 1 day to refresh again.