Publish your SDKs

Once you are satisfied with your SDK, you can distribute it to end users by publishing it to a package registry, like npm, PyPI, or RubyGems. After publishing, the generated SDK code will be moved to a GitHub repository that you own, where it will be picked up by package registries.

The Stainless-managed release flow handles the versioning and changelogs expected from a production-quality SDK. You can even automate this process so changes to your OpenAPI specification will trigger new releases.

1 Link production repos

Before you publish an SDK, we push the generated code to a staging repo under the stainless-sdks GitHub organization. When your SDK is published, we instead push the generated SDK code to a GitHub repo you own, called the production repo.

Install the Stainless GitHub app

If your Stainless organization does not already have the Stainless GitHub app installed, you’ll need to install it first.

1. In the Stainless dashboard, navigate to your project.
2. Navigate to Release > Production repos.
3. Follow the installation flow. When prompted, select which repos the Stainless GitHub app can access.
4. Once repos have been selected and permissions have been reviewed, click Install & Authorize.

By default All repositories is selected, but we recommend you only select the repos you plan to use for Stainless SDKs.

Choose a production repo

After installing the Stainless GitHub app, you can then choose or create the production repo for each SDK.

We recommend choosing a name that meaningfully identifies your SDK. For example, <company-name>-python is a common choice for Python SDKs.

The repo can be public or private.

1. In the Stainless dashboard, navigate to your project.
2. Navigate to Release > Production repos.
3. If the Stainless GitHub app is installed, you will see a list of languages for your project. For each SDK you want to publish, use the dropdown to choose or create its production repo.
4. Optionally, configure which branch of the production repo to push code to, by selecting it from the dropdown next to the repo name.

You need a choose a different GitHub repo for each language: one for TypeScript, one for Python, and so on.

The production repo for a Terraform provider must be in the form terraform-provider-<name>.

2 Connect package registries

Package registries like npm and PyPI make it easy to distribute your packages to your users. After an initial setup, Stainless can automatically publish code from your production repo to various package registries.

Node/TypeScript: npm

Get an access token

1. Log in or sign up at npm.

2. Select your profile picture on the top right to open a dropdown.

3. Navigate to Access Tokens > Generate New Token.

4. Choose a token version:

   • Classic Token, with Automation as the token type. This token will be scoped to your whole account.

   • Granular Access Token, scoped to the NPM package you’re publishing. The token needs read and write permissions. If you don’t have an existing NPM package, you can make an empty one as a starting point.

Add the token to your production repo

1. In the production repo, navigate to Secrets and variables > Actions > New repository secret. The URL should look like https://github.com/<org>/<repo>/settings/secrets/actions/new.
2. Add a new secret named NPM_TOKEN with your API token.

Choose a package name and update your Stainless config

1. Choose an available package name.

   You can make your package organization scoped (@<company-name>/<package-name>), but you will need to use a Granular Access Token that has Read and Write permissions for the right NPM organization. Trying to publish an organization scoped package using a Classic Token will result in an error.

   You can check if the name is available.

   If you are using an existing NPM package, check the publishing access, under package settings, so that it doesn’t require two-factor authentication.

2. Update the Stainless config with your package name and save.

   targets:
     typescript:
       package_name: <package-name>
       publish:
         npm: true

Deno: JSR

Create a JSR package

1. Log in or sign up at JSR.
2. Select Publish a package.
3. Choose an appropriate scope and package name.
4. Select Create.

(Option 1) Publish with GitHub OIDC

1. In JSR, navigate to <package-name> > Settings > GitHub Repository.

2. Link the production repo to the JSR package you created.

3. Navigate to your <scope-name> > Settings > GitHub Actions security.

4. Select Do not restrict publishing. This will let the Stainless GitHub App publish even though it is not a member of your scope.

5. Update the Stainless config with your package name and save.

   targets:
     typescript:
       publish:
         jsr:
           package_name: @<scope-name>/<package-name>

(Option 2) Use access token to publish

1. In JSR, navigate to Account > Tokens > Personal access tokens > Create new token.

2. Navigate through wizard to get your token:

   1. Publish packages
   2. A development machine
   3. Create a token
   4. Create a token for the package name.

3. In your production repo, navigate to Secrets and variables > Actions > New repository secret. The URL should look like https://github.com/<org>/<repo>/settings/secrets/actions/new.

4. Add a new secret named JSR_TOKEN with your API token.

5. Update the Stainless config with your package name and use_access_token, and save.

   typescript:
     package_name: <package-name>
     publish:
       npm: true
       jsr:
         package_name: @<scope-name>/<package-name>
         use_access_token: true

Python: PyPI

Get an API token

1. Log in or sign up at PyPI.

2. Select your profile picture on the top right to open a dropdown.

3. Navigate to Access settings > API tokens > Add API token. You may have to verify your email address and set up 2FA if you haven’t already done so.

   Note: If you haven’t created a PyPI package yet, you can create an API token scoped to your whole account, or you can create an empty PyPI package to use as a starting point.

Add the token to your production repo

1. In your production repo, navigate to Secrets and variables > Actions > New repository secret. The URL should look like https://github.com/<org>/<repo>/settings/secrets/actions/new.
2. Add a new secret named PYPI_TOKEN with your API token.

Choose a package name and update your Stainless config

1. Choose an available package name. Suggested names are:

   • <company-name>
   • <company-name>-client

   You can check whether the name is available by testing the link at https://pypi.org/project/<package-name>.

2. Update the Stainless config with your package name and save.

   targets:
     python:
       package_name: <package-name>
       publish:
         pypi: true

Go: GitHub

Go installs packages from source, so nothing other than the GitHub repository is required for setup. We automatically request updates from the Go package index which updates your godoc on a release.

Java/Kotlin: Sonatype Maven Central

We publish JVM packages to Sonatype. Sonatype has both a legacy (OSSRH) publishing flow and a new Central Portal publishing flow.

If you do not already publish to OSSRH, you will most likely have to use the new Central Portal publishing flow. If you are already publishing to OSSRH, you can continue to do so.

Setting up Sonatype can be an involved process. We recommend you go through this process after getting your SDKs into a satisfactory state.

Update your Stainless config (Central Portal only)

For backwards compatibility, the default sonatype_platform is ossrh. If you are using the Central Portal, you need to update the Stainless config to portal:

targets:
  java:
    reverse_domain: com.example.api
    publish:
      maven:
        sonatype_platform: portal

Add namespace (Central Portal only)

1. Add a namespace on Sonatype Portal

   The namespace will be part of your package’s name. It will be the inverse of the domain that you own. i.e. tld.domain.subdomain

2. Copy the Verification Key

   You will be able to prove your ownership of the namespace by adding a TXT record of the verification key to your domain.

Prove ownership over your domain

Add a temporary TXT record to the DNS for your primary domain (the reverse of your groupId) to verify that the person registering this Java group actually controls the domain.

If using the Central Portal flow, the contents of the TXT record is the verification key provided by Sonatype.

If using the OSSRH flow, the contents of the TXT record is the ID of the JIRA ticket created in the previous step (for example, OSSRH-12345).

Generate user token (Central Portal only)

From the Sonatype dashboard, generate a user token XML file.

Extract <username>…</username> and <password>…</password> from the XML file and store them somewhere secure.

<server>
  <id>${server}</id>
  <username>//P7KNy5</username>
  <password>+8sEiCiUrSoODM/S4yFhiKqUWJzS1lDbcac5I7hVzPS4</password>
</server>

Generate a PGP key

1. Install GnuPG.

2. In a terminal, run gpg --gen-key. Enter your name, email, and a passphrase for the keypair.

3. Run gpg --list-keys --keyid-format short:

   % gpg --list-keys --keyid-format short
   [keyboxd]
   ---------
   pub   ed25519/7FAD9FAA 2023-08-02 [SC] [expires: 2026-08-01]
         418D41921938A753CAAE57985114AD037FAD9FAA
   uid         [ultimate] Your Organization <you@yourorg.com>
   sub   cv25519/07EB38A7 2023-08-02 [E] [expires: 2026-08-01]

4. Export the key in ASCII-armored format. In the above example, the short key ID is 7FAD9FAA.

   $ gpg --export-secret-keys --armor 7FAD9FAA
   -----BEGIN PGP PRIVATE KEY BLOCK-----
   
   lIYEZMpnEhYJKwYBBAHaRw8BAQdA1FQMKz+wwliKNdLehegZP0QiaKrZJqADNyVn
   VCUzIrD+BwMCwZrqVbVPfSr8NwxEh3M6kWtMGmnLMOk/NWVe7dtCxDxo37l/Ncxj
   Mm9EZiH6WXwoXXq20nOW354oNOVz/UPvDU+oaRDDUM9SYs392i69WLQjWW91ciBP
   cmdhbml6YXRpb24gPHlvdUB5b3Vyb3JnLmNvbT6ImQQTFgoAQRYhBEGNQZIZOKdT
   yq5XmFEUrQN/rZ+qBQJkymcSAhsDBQkFo5qABQsJCAcCAiICBhUKCQgLAgQWAgMB
   Ah4HAheAAAoJEFEUrQN/rZ+qgtsBAMCBuTqYEJljxStRO7SsMLWOc47CIIXD0Yid
   CbySBX0ZAP9DXuuGVYbHFONvHxNKszu2hY9A1BbRuNjeGeWuVOw9ApyLBGTKZxIS
   CisGAQQBl1UBBQEBB0AFxkZ+ZdEN7Epwri/w5ETAf+MOqdwAP2sS6TccSjEiXQMB
   CAf+BwMCtKG1TBUSC/z8tn761I5j+ifVIuMqdQPYIhZtjvIyC+NyrBi0j1ZtUG4A
   DAeDKNyM63uyb7omOH8+Lu0J71SGhVnZWszUOf3rrT/TA5MktYh+BBgWCgAmFiEE
   QY1Bkhk4p1PKrleYURStA3+tn6oFAmTKZxICGwwFCQWjmoAACgkQURStA3+tn6qa
   XAD/W2ucVURngmCUiUtdjQAZz36yQYPQmBhcdabZMyXKHz0A/itwYkuRbD2mp4p/
   xJk/QLXs/2/xBA6s0ROVVspy6MEA
   =p/g/
   -----END PGP PRIVATE KEY BLOCK-----

5. Publish your PGP public key.

   $ gpg --keyserver keyserver.ubuntu.com --send-keys 7FAD9FAA

   If you get the following error:

   gpg: sending key XXXXXX to hkp://keyserver.ubuntu.com
   gpg: keyserver send failed: No route to host

   then your computer might be trying to use IPv6 and failing. Run the following to get keyserver.ubuntu.com’s IPv4 addresses:

   $ host keyserver.ubuntu.com
   keyserver.ubuntu.com has address XXX.XXX.XXX.XX
   keyserver.ubuntu.com has address XXX.XXX.XXX.XX
   keyserver.ubuntu.com has IPv6 address XXXX:XX:XXXX:XXXX::XXX
   keyserver.ubuntu.com has IPv6 address XXXX:XX:XXXX:XXXX::XXX

   Then rerun the gpg command with one of the IPv4 addresses:

   $ gpg --keyserver XXX.XXX.XXX.XX --send-keys 7FAD9FAA

Add secrets to your production repo

1. In the production repo, navigate to Secrets and variables > Actions > New repository secret. The URL should look like https://github.com/<org>/<repo>/settings/secrets/actions/new.
2. Add the following secrets:

• GPG_SIGNING_KEY: your PGP private key. It should be the entire output of gpg --export-secret-keys --armor <keyid>.

• GPG_SIGNING_PASSWORD: the passphrase you entered when creating the keypair.

• SONATYPE_USERNAME: username for your Sonatype account.

• SONATYPE_PASSWORD: password for your Sonatype account (OSSRH) or your Sonatype user token (Central Portal).

Ruby: RubyGems

Get an API token

1. Log in or sign up at RubyGems.
2. Select your profile picture on the top right to open a dropdown.
3. Navigate to Settings.
4. If you have MFA enabled, set the level to “UI and gem signin”.
5. Navigate to API keys.
6. Create a new API key with the “Push rubygems” privilege. If you have MFA enabled, make sure “Enable MFA” is unchecked.

Add the token to your production repo

1. In your production repo, navigate to Secrets and variables > Actions > New repository secret. The URL should look like https://github.com/<org>/<repo>/settings/secrets/actions/new.
2. Add a new secret named GEM_HOST_API_KEY with your API token.

Choose a package name and update your Stainless config

1. Choose an available package name. Suggested names are:

   • <company-name>
   • <company-name>-client

   You can check whether the name is available by testing the link at https://rubygems.org/gems/<package-name>.

2. Update the Stainless config with your package name and save.

   targets:
     ruby:
       gem_name: <package-name>
       publish:
         rubygems: true

PHP: Packagist

Set the Composer package name in the Stainless config

Set composer_package_name before proceeding other steps.

Navigate to the targets section of your stainless config, and ensure it resembles the following.

targets:
  php:
    package_name: acme
    composer_package_name: 'acme-org/acme-php' # <- Packagist installation name
    publish:
      packagist: true

The composer_package_name will appear in Packagist. Make sure that the name follows the convention of the Composer specification, which is roughly equivalent to vendor/package-name.

The composer_package_name name must be available on Packagist.

The package_name is used within the SDK, e.g. to name the client class AcmeClient { ... }.

The packagist name is used by the ecosystem, e.g. composer require acme-org/acme-php.

Set up a Packagist account and package

1. Log in or sign up at Packagist.
2. Navigate into your profile by clicking on your username in the top right corner.
3. Navigate to the “Settings” section of your profile, and ensure your account is connected via Github.
4. Click the “Submit” button at the top and add your production Github repository, and follow the packagist instructions.

Packagist requires that your production repository is public in order to publish packages. Private repositories are not supported for Packagist publishing.

Find your Packagist “Safe API Token”

1. Ensuring you are signed in on Packagist, click on your username in the top right corner.
2. Ensure the sidebar is set to the “Profile” section.
3. Click the “Safe API Token” tab, it is not necessary to use the “Main API Token”. However it must remain

Add secrets to your production repo

1. Ensure your Github actions environment has your Stainless API Key
2. In the production repo, navigate to Secrets and variables > Actions > New repository secret. The URL should look like https://github.com/<org>/<repo>/settings/secrets/actions/new.
3. Add the following secrets:

• PACKAGIST_SAFE_KEY: Your Packagist Safe API Token

• PACKAGIST_USERNAME: Your username in Packagist as it appears in the top-right corner.

Terraform: Terraform Registry

The following steps allow you to publish your provider to the registry. If you have more custom requirements, you can also refer to the official HashiCorp publishing documentation.

Connect Terraform Registry to your production repo

1. Log in or sign up at the Terraform Registry.
2. Select Publish Provider.
3. Follow the instructions to install the Hashicorp GitHub App.
4. In the provider publishing page, select the connected user / organization.
5. Select your production repo and follow the instructions to install the webhooks required to publish the provider.

Generate a PGP key

1. Install GnuPG.

Note: The Terraform Registry API accepts both RSA and DSA keys, but not the default ECC type.

1. In a terminal, run gpg --full-generate-key. Follow the prompts to select an RSA/DSA key, and input your organization’s information.

2. Run gpg --list-keys --keyid-format short:

   % gpg --list-keys --keyid-format short
   [keyboxd]
   ---------
   pub   rsa3072/69568313 2025-03-22 [SC] [expires: 2025-03-23]
         1577714D2E1545CC87291B3A1703FF1469568313
   uid         [ultimate] Your Organization <you@yourorg.com>
   sub   rsa3072/26D93FE8 2025-03-22 [E] [expires: 2025-03-23]

3. Export the key in ASCII-armored format. In the above example, the short key ID is 69568313.

   $ gpg --export-secret-keys --armor 69568313
   -----BEGIN PGP PRIVATE KEY BLOCK-----
   
   lQWGBGffFm0BDADEUBBMBLQ2qRg8YPKBln9VKolAcFiq6CwehhnHw1B8xr9BiVnY
   0ekDmOkAWIhU1zG+AFULhsvWowld55pMglPW1Mptpfb2AqJdbglr2iStUjSn+Jn1
   riRKaP3YQErtV0/dBRFcM8F4LdGK8NhSYnrEyGb1eFCBawHxU/P09+Otcxs+9mvy
   jSFiWBrrK45H62sDQq2HYrjLXcytD0WpqLAxgxLN6cGwtwmfd6TAMQeJ248Qa97M
   ...
   CriOVP9mAUyhez1k6tuVi5U0mDp9KeMj3zJcsTjTEvqe+8wQQoRgtqyY60yXkJJ6
   HvapRVLjxiU8/x+VltFn7sxm+LDoSEc8hcsIrT19uIyA4HOEo9etJI/VT31Tt39S
   XW4n8ELhMIdxDq0jZp/93ONsPBmjZ0L/qbDH6ytT0FSEuSt05CY7
   =VDjv
   -----END PGP PRIVATE KEY BLOCK-----

4. Publish your PGP public key.

   $ gpg --keyserver keyserver.ubuntu.com --send-keys 69568313

   If you get the following error:

   gpg: sending key XXXXXX to hkp://keyserver.ubuntu.com
   gpg: keyserver send failed: No route to host

   then your computer might be trying to use IPv6 and failing. Run the following to get keyserver.ubuntu.com’s IPv4 addresses:

   $ host keyserver.ubuntu.com
   keyserver.ubuntu.com has address XXX.XXX.XXX.XX
   keyserver.ubuntu.com has address XXX.XXX.XXX.XX
   keyserver.ubuntu.com has IPv6 address XXXX:XX:XXXX:XXXX::XXX
   keyserver.ubuntu.com has IPv6 address XXXX:XX:XXXX:XXXX::XXX

   Then rerun the gpg command with one of the IPv4 addresses:

   $ gpg --keyserver XXX.XXX.XXX.XX --send-keys 69568313

Add secrets to your production repo

1. In the production repo, navigate to Secrets and variables > Actions > New repository secret. The URL should look like https://github.com/<org>/<repo>/settings/secrets/actions/new.
2. Add the following secrets:

• GPG_SIGNING_KEY: your PGP private key. It should be the entire output of gpg --export-secret-keys --armor <keyid>.

• GPG_SIGNING_PASSWORD: the passphrase you entered when creating the keypair.

Update your Stainless config

1. Update the Stainless config and save.

   targets:
     terraform:
       publish:
         hashicorp_registry: true

Merge your release PR and see it appear in the Registry

• Merge your release PR when you’re ready. This should then create a tag, use goreleaser to build artifacts, and attach it to the release. Hashicorp will then import the release into their registry. You might need to wait a few minutes for it to show up on your provider page.

C#: NuGet

Get an API token

1. Log in or sign up at NuGet.
2. Select your username at the top right to open a dropdown.
3. Navigate to API Keys.
4. Create a new API key with the Push new packages and package versions privilege. Under Select Packages, either enter your package name or a glob (e.g. ”*”).

Add the token to your production repo

1. In your production repo, navigate to Secrets and variables > Actions > New repository secret. The URL should look like https://github.com/<org>/<repo>/settings/secrets/actions/new.
2. Add a new secret named NUGET_API_KEY with your API token.

Choose a package name and update your Stainless config

1. Choose an available package name. Suggested names are:

   • <company-name>
   • <company-name>.Client

   You can check whether the name is available by testing the link at https://www.nuget.org/packages/<package-name>.

2. Update the Stainless config with your package name and save.

   targets:
     csharp:
       package_name: <package-name>
       publish:
         nuget: true

Versioning and releases

Whenever your SDK changes because of an update to your OpenAPI spec, your Stainless config, or our code generation, we push the changes to the next branch of your production repository.

A release PR is then created against the main branch, which collects individual changes as commits until you are ready to release them. By default, we will never merge release PRs until they’re reviewed. This leaves the release frequency up to you.

Your first release will be Release 0.1.0-alpha.1, meaning that the first release published to your package manager will have an alpha tag.

Stainless will increment the version used in each subsequent release PR based on the prior one. We use the semantic information of the commits in the release to find the next available version, and for this reason commits should use the Conventional Commits to ensure versioning is correctly and automatically incremented:

• Breaking changes increment the major version number (if and only if the version is already at least 1.0.0)
• Features increment the minor version number
• Fixes increment the patch number

How to customize the release version

You can override our suggested version by modifying the PR title. Doing so will propagate your provided version (including any alpha or beta tags) to the release in Github and your package manager. We recommend:

• Staying in the alpha or beta stage while your SDKs still have diagnostic errors
• Staying in the 0.0.x range while your SDKs still have diagnostic warnings
• Staying in the 0.x.y range while your SDKs still have unacknowledged diagnostic notes
• Moving to 1.0.0 once your SDK has none of the above

We use semver-valid version numbers for releases.

How to move out of alpha

Once you’re ready to move out of an alpha stage, the only thing you need to do is customize the release version to the appropriate version. In most cases the next version after alpha should be 0.0.1.

If you don’t have a release PR, you can make an empty commit on the next branch of your production repo with a Conventional Commit message.

Development and release flow

Stainless pushes code to various GitHub repos:

1. Stainless config repo
2. Stainless SDK repos
3. Your production repos

Release flow

Stainless uses a few branches in your production repository to manage the release process:

• main/master: The target branch of your repository. This defaults to main but can be configured per language using production_repo.
• next: This branch is used to collect changes for the next release. Stainless will create Release PRs based on the changes in this branch.
• generated: The branch where Stainless pushes generated code from the Studio. This branch represents the latest generated code before any custom code changes are applied.
• release-please--*: Temporary release branches created and managed by our GitHub App. These branches are based on next and are used to create release PRs.